Developer Documentation

Introduction

ONTO Wallet Documentation provides technical reference and practical guidance for developers building applications and services on the Ontology blockchain.

This documentation covers core concepts, APIs, SDK usage, and common integration patterns required to interact with Ontology wallets, accounts, identities, and smart contracts. It is intended for developers who want to integrate ONTO Wallet into their applications or build directly on top of the Ontology network.

The examples and references in this documentation focus on clear, minimal implementations. They are designed to help you understand how wallet interactions, transactions, and identity-related features work at a protocol and application level.

What you can do with this documentation

Using the materials provided here, you can:

• Integrate ONTO Wallet into desktop or browser-based applications
• Manage wallets, accounts, and addresses programmatically
• Sign and submit transactions to the Ontology blockchain
• Work with ONT ID and decentralized identity features
• Interact with smart contracts deployed on Ontology

Who this documentation is for

This documentation is intended for:

• Application developers integrating ONTO Wallet functionality
• Backend engineers working with Ontology transactions and accounts
• Developers building tools, services, or dApps on Ontology
• Technical users who need low-level control over wallet operations

Quick Start

This section walks you through the basic steps required to start using Ontology Wallet. It explains how to create or import a wallet, manage accounts, and perform basic on-chain actions. No prior blockchain experience is required.

Step 1: Install Ontology Wallet

Download and install Ontology Wallet for your operating system from the official download page.

Ontology Wallet is available for desktop platforms (Windows, macOS, Linux). After installation, launch the application to begin setup.

Step 2: Create or Import a Wallet

Ontology Wallet is available for desktop (Windows, macOS, Linux) and mobile platforms. After installation, launch the application to begin setup.

Create a New Wallet

Choose this option if you are setting up a wallet for the first time.

Select Create Wallet and complete the following steps:

• Set a wallet name to help you identify it locally
• Generate a recovery phrase
• Write down the recovery phrase and store it securely
• Confirm the recovery phrase to complete wallet creation

Import an Existing Wallet

Choose this option if you already have a wallet.

Select Import Wallet and follow these steps:

• Choose an import method
• Recovery phrase
• Private key
• Enter the required information
• Assign a local wallet name
• Complete the import process

Once imported, the wallet will display all associated accounts and balances.

Step 3: Understanding Wallets and Accounts

A wallet is a container that holds one or more accounts. Each account corresponds to a blockchain address.

Within Ontology Wallet, you can:

• Create multiple accounts under a single wallet
• Switch between accounts
• View balances and transaction history per account

Accounts are generated locally and do not require any on-chain registration before use.

Step 4: Sending and Receiving Assets

To receive assets:

• Select an account
• Copy the account address
• Share the address with the sender

To send assets:

• Select an account
• Choose Send
• Enter the recipient address
• Specify the amount
• Review transaction details
• Confirm and sign the transaction

All transactions must be approved locally before they are broadcast to the network.

Step 5: Interacting With the Blockchain

Ontology Wallet allows you to perform on-chain operations directly, including:

• Signing transactions
• Approving smart contract calls
• Interacting with decentralized applications
• Participating in supported protocol-level actions

Each operation requires explicit confirmation before execution.

Step 6: Restoring a Wallet

If you reinstall the application or move to a new device, you can restore your wallet at any time using your recovery phrase or private key.

Follow these steps:

• Install Ontology Wallet
• Select Import Wallet
• Enter your recovery phrase or private key
• Confirm the import

All accounts associated with the wallet will be restored automatically.

Wallet Architecture

Ontology Wallet is designed as a client-side application that manages cryptographic keys, accounts, and on-chain interactions locally on the user’s device. The wallet acts as an interface between the user or application and the Ontology blockchain, enabling secure key management, transaction signing, and interaction with smart contracts and decentralized identity features.

All sensitive operations, including key generation, storage, and transaction signing, are performed locally. Ontology Wallet does not custody user assets, private keys, or recovery phrases, and it does not require user registration or centralized account management. This architecture ensures that users and applications retain full control over their wallets while interacting directly with the Ontology network.

From an architectural perspective, the wallet is composed of three core layers:

• Key and account management, responsible for generating and storing cryptographic material
• Transaction and contract interaction, handling signing and submission of on-chain actions
• Application interface, exposing wallet functionality to users and integrated applications

This separation allows Ontology Wallet to support both direct user interaction and programmatic integration by applications and services.

Wallet vs Account

In Ontology Wallet, the terms wallet and account represent two distinct but closely related concepts.

A wallet is a logical container that manages one or more accounts. It serves as the highest-level unit for key storage and recovery. Each wallet is created or restored using a recovery phrase or private key material and exists entirely on the local device.

An account represents a single blockchain identity within a wallet. Each account corresponds to a unique address on the Ontology blockchain and is associated with its own cryptographic key pair.

Key differences between wallets and accounts:

• A wallet can contain multiple accounts
• Each account has one address and one key pair
• Wallet-level recovery restores all associated accounts
• Accounts can be created or removed without affecting other accounts in the same wallet

This structure allows users and applications to organize blockchain activity logically. For example, a single wallet may contain separate accounts for operational use, testing, or different application contexts, while still being backed up and restored as a single unit.

From a developer perspective, this model enables:

• Managing multiple addresses under a single recovery mechanism
• Isolating application-specific accounts while sharing wallet-level security
• Programmatically switching accounts without reinitializing the wallet

Accounts are generated locally and do not require any on-chain registration before use. An account becomes active on-chain only when it is used to sign and submit a transaction.

Accounts & Keys

Ontology Wallet manages access to the Ontology blockchain through cryptographic keys that are generated and stored locally on the user’s device. These keys form the foundation of account ownership, transaction authorization, and identity-related operations on the network.

Each account in Ontology Wallet is controlled by a unique cryptographic key pair. The wallet never transmits private keys off the device and does not rely on centralized key storage or external custody services. All key management and signing operations are performed locally.

Key Types and Structure

Each account is based on an asymmetric cryptographic key pair consisting of:

• Private key — Used to sign transactions and authorize on-chain actions.
• Public key — Derived from the private key and used to verify signatures.
• Address — A human-readable blockchain identifier derived from the public key and used to receive assets and interact with smart contracts.

The private key is the most sensitive element in this structure. Control of the private key represents full control over the account and any assets or permissions associated with it.

Ontology Wallet uses industry-standard cryptographic algorithms supported by the Ontology blockchain. Key generation occurs locally during account creation or wallet import.

Account Creation

When creating a new account, Ontology Wallet performs the following operations locally:

• Generates a new private key using a secure random source
• Derives the corresponding public key from the private key
• Generates a blockchain address from the public key
• Stores the encrypted private key within the wallet environment

Accounts can be created at any time within an existing wallet. Creating a new account does not affect other accounts and does not require any interaction with the blockchain.

An account becomes visible on-chain only after it is used to sign and submit a transaction.

Recovery Phrase and Key Backup

When a wallet is created, Ontology Wallet generates a recovery phrase (also referred to as a mnemonic phrase). This phrase represents the root key material required to restore the wallet and all associated accounts.

Key characteristics of the recovery phrase:

• It can restore all accounts within a wallet
• It is generated only once during wallet creation
• It is not stored or transmitted by Ontology Wallet
• Anyone with access to the phrase can fully control the wallet

Importing Accounts and Keys

Ontology Wallet supports importing existing wallets or accounts using different types of key material, including:

• Recovery phrases
• Raw private keys

During the import process, the wallet reconstructs cryptographic keys locally and re-associates all corresponding blockchain addresses. No on-chain operation is required during import.

Once imported, accounts function identically to newly created accounts and can be used immediately to interact with the Ontology blockchain.

Smart Contracts Overview

Smart contracts on the Ontology blockchain are programs deployed on-chain that define rules for asset transfers, application logic, and automated operations. These contracts execute deterministically on the network and can be interacted with by users and applications through signed transactions.

Ontology Wallet provides the interface required to interact with smart contracts. It does not execute contract logic itself but enables users and applications to call contract methods, submit transactions, and approve on-chain actions in accordance with protocol rules.

Smart Contract Interaction Model

Interaction with a smart contract on Ontology follows a standard blockchain pattern:

• A contract is deployed on-chain at a specific address
• The contract exposes callable methods defined in its code
• Users or applications invoke these methods by submitting signed transactions
• The blockchain executes the contract logic and records the result

Ontology Wallet acts as a signing and submission layer in this process, ensuring that all contract interactions are explicitly authorized by the account owner.

Read and Write Operations

Smart contract interactions can be broadly categorized into two types:

• Read operations — Retrieve data from the contract state without modifying blockchain data. These operations do not require transaction fees and do not change on-chain state.
• Write operations — Modify contract state or trigger on-chain actions. These operations require a signed transaction and payment of network fees.

Ontology Wallet distinguishes between these interaction types and only requires transaction approval and signing when a write operation is performed.

Contract Invocation and Authorization

When a contract method requires a state change, Ontology Wallet prepares a transaction that includes:

• The contract address
• The method being invoked
• The required input parameters
• Fee and execution parameters

Before submission, the wallet presents the transaction details for review. Execution only occurs after the transaction is signed by the selected account.

This authorization step ensures that contract interactions cannot occur without explicit user or application consent.

Fees and Execution Costs

Smart contract execution on Ontology consumes network resources and requires fees paid in ONG. The exact cost depends on the complexity of the contract logic and the resources consumed during execution.

Ontology Wallet does not set execution costs. It displays fee-related information provided by the network and includes the required fees as part of the transaction submission process.

ONT ID Basics

ONT ID is the decentralized identity framework of the Ontology blockchain. It provides a way to represent identities on-chain using cryptographic keys and smart contract–based authorization, without relying on centralized identity providers.

An ONT ID functions as a decentralized identifier that can be linked to accounts, permissions, and identity-related actions. Control over an identity is established through cryptographic signatures rather than usernames, passwords, or off-chain databases. This allows identities to be owned and managed directly by users or applications.

Ontology Wallet serves as the primary interface for working with ONT ID. It enables the creation of identities, authorization of identity-related actions, and signing of identity transactions locally on the user’s device.

ONT ID Structure

At a technical level, an ONT ID consists of a unique identifier associated with one or more cryptographic keys and a set of authorization rules enforced on-chain. These rules determine which keys are allowed to perform specific identity operations, such as updates or delegated actions.

Public key references associated with an ONT ID are used by the network to verify signatures. Identity-related metadata and permissions are managed through smart contracts deployed on the Ontology blockchain, ensuring deterministic and verifiable behavior. Ownership of an ONT ID is proven exclusively through cryptographic signatures generated by authorized private keys.

Identity Creation and Management

Creating an ONT ID requires an on-chain transaction that registers identity data and authorization rules. Ontology Wallet facilitates this process by generating identity-related keys locally and signing the required transactions before submission to the network.

Once an identity is created, it can be updated or managed through additional signed transactions. These operations may include adding or removing keys, updating authorization rules, or modifying identity-related references. All changes are recorded on-chain and are subject to the network’s confirmation rules.

Ontology Wallet does not store identity data on behalf of users. It provides signing and submission capabilities while leaving identity state and enforcement to the blockchain.

Authorization and Delegation

ONT ID supports flexible authorization models that allow identity owners to define how control is exercised. Multiple keys can be associated with a single identity, each with specific permissions. This enables scenarios such as delegated access, application-level authorization, or separation of administrative and operational roles.

Authorization rules are enforced at the protocol level through smart contracts. Ontology Wallet ensures that identity-related actions are only executed after proper authorization and signature validation.

ONT ID in Applications

Applications can integrate ONT ID to enable decentralized identity workflows without maintaining centralized user accounts. Identity-based authorization can be used to control access, verify credentials, or authorize on-chain actions within applications.

In these scenarios, Ontology Wallet acts as the signing and authorization layer. Applications request identity actions, while the wallet ensures that users explicitly approve and sign all identity-related operations.

SDK Setup

This section explains how to set up the Ontology SDK and prepare your development environment for interacting with Ontology Wallet and the Ontology blockchain. It covers basic installation and initialization required before performing wallet, transaction, or smart contract operations.

Ontology provides official SDKs for interacting with the network. These SDKs are used by applications to construct transactions, interact with smart contracts, and communicate with Ontology nodes, while Ontology Wallet is responsible for signing and user authorization.

Requirements

Before installing the SDK, ensure that your development environment meets the following requirements:

• Node.js (LTS version recommended)
• npm or yarn package manager
• Basic understanding of JavaScript and asynchronous programming
• Access to an Ontology RPC endpoint (public or self-hosted)

Ontology Wallet must be installed and available if your application relies on wallet-based signing

Installing the SDK

Install the official Ontology JavaScript SDK using npm:

npm install ontology-ts-sdk

Or using yarn:

yarn add ontology-ts-sdk

Once installed, the SDK can be imported into your project and used to construct blockchain interactions.

Initializing the SDK

The first step is to configure a connection to an Ontology node. This allows your application to query blockchain data and submit signed transactions.

import { RestClient } from 'ontology-ts-sdk';

const rpcUrl = 'https://dappnode1.ont.io:20334';
const client = new RestClient(rpcUrl);

The RestClient instance is used for network communication such as sending transactions, querying blocks, or retrieving contract state.

Preparing Wallet Interaction

In a typical integration flow:

• Your application constructs a transaction or contract call using the SDK
• The transaction data is passed to Ontology Wallet
• Ontology Wallet signs the transaction using the selected account
• The signed transaction is submitted to the network

At this stage, your application does not manage private keys directly. Key management and signing are delegated to Ontology Wallet.

Example: Building a Simple Transaction Payload

The SDK can be used to construct transaction data before it is signed by the wallet.

import { TransactionBuilder, TxType } from 'ontology-ts-sdk';

const tx = TransactionBuilder.makeTransferTransaction(
  'ONT',
  fromAddress,
  toAddress,
  amount,
  gasPrice,
  gasLimit
);

The resulting transaction object can then be forwarded to Ontology Wallet for review and signing.

Wallet Integration

This section describes how applications integrate with Ontology Wallet to request transaction signing and user authorization. Ontology Wallet acts as an external signing provider that securely manages keys and requires explicit user approval for all on-chain actions.

Applications never access private keys directly. Instead, they construct transaction or contract payloads and delegate signing to the wallet.

Integration Model Overview

The integration between an application and Ontology Wallet follows a request–response model:

1. The application prepares a transaction or contract call using the SDK
2. The request is sent to Ontology Wallet
3. The wallet displays the request details to the user
4. The user approves or rejects the request
5. If approved, the wallet signs the request and returns the result

This model ensures that all sensitive operations are performed inside the wallet environment and explicitly authorized by the user.

Wallet Availability and Connection

Before initiating any wallet-related operation, the application must ensure that Ontology Wallet is available and accessible in the current environment. Depending on the integration context, this may include:

• Detecting a locally installed wallet application
• Establishing a communication channel between the application and the wallet
• Verifying that at least one account is available for signing

If the wallet is not available or the user has no active account, the application should handle this state gracefully and prompt the user to take appropriate action.

Requesting Account Information

Applications often need basic account data before constructing transactions, such as the active address or network information. A typical account request flow includes:

• Requesting the currently selected account
• Receiving the account address and public key
• Using this information to prepare transaction payloads

Account information requests do not require signing but may still require user consent depending on wallet settings.

Transaction Request Flow

When an application needs to perform an on-chain action, it must request signing from Ontology Wallet. The general flow is as follows:

• Construct the transaction using the Ontology SDK
• Pass the unsigned transaction data to the wallet
• Wait for user approval
• Receive the signed transaction
• Submit the signed transaction to the network

The wallet is responsible for validating the request format, displaying transaction details, and handling user approval.

Example: Sending a Transaction for Signing

// Pseudocode example
const unsignedTx = buildTransactionPayload{
  from: userAddress,
  to: recipientAddress,
  amount,
  gasPrice,
  gasLimit
};

// Send transaction to Ontology Wallet for signing
const signedTx = await requestWalletSignature(unsignedTx);

// Submit signed transaction
await client.sendRawTransaction(signedTx);

The exact communication mechanism depends on the integration method and environment. Applications should treat the wallet as an external signer and avoid assumptions about internal wallet state.

Handling User Approval and Rejection

Ontology Wallet requires explicit user action for all signing requests. Applications must be prepared to handle both approval and rejection scenarios. Common cases include:

• User approves the request and the transaction is signed
• User rejects the request
• Wallet is locked or unavailable
• Request times out or is canceled

Applications should provide clear feedback to users and avoid retrying requests automatically without user interaction.

dApp Integration

This section explains how decentralized applications (dApps) integrate with Ontology Wallet to interact with the Ontology blockchain. Ontology Wallet serves as the secure authorization and signing layer, while the dApp remains responsible for application logic, user interaction, and transaction construction.

In an Ontology-based application, the dApp never manages private keys directly. Instead, it prepares transaction or contract invocation data and requests user authorization through Ontology Wallet. This separation ensures that sensitive key material remains isolated within the wallet environment and under direct user control.

A typical dApp integration follows a request-driven model. When a user initiates an action in the application—such as submitting a transaction or interacting with a smart contract—the dApp constructs the required payload using the Ontology SDK. This payload is then forwarded to Ontology Wallet, which presents the details to the user for review. Only after explicit user approval does the wallet sign the request and return the signed result to the application.

Once a signed response is received, the dApp submits it to the Ontology network and monitors the transaction status. Because blockchain operations are asynchronous, applications must be designed to handle delayed confirmations, failed executions, and intermediate states such as pending transactions. User interfaces should reflect these states clearly and avoid assuming immediate success.

Ontology Wallet may also be used in identity-aware applications through ONT ID. In such cases, the dApp requests identity-related actions from the wallet, such as identity authorization or proof generation. The wallet signs these requests locally, and the application consumes the resulting on-chain data or verification outcome. This enables decentralized authentication flows without centralized user accounts or off-chain credential storage.

Error handling is an important aspect of dApp integration. Applications must account for scenarios where the wallet is not available, no account is selected, the user rejects a request, or the network returns an error. These cases should be treated as expected outcomes rather than exceptional failures and handled gracefully within the application flow.

From a design perspective, successful dApp integrations prioritize transparency and user intent. Signing requests should be minimal, clearly scoped, and directly tied to user actions. Applications should avoid bundling unrelated operations into a single request or attempting to automate approvals without user awareness.

API Reference

This section provides a technical reference for interacting with the Ontology blockchain using the official Ontology SDK in combination with Ontology Wallet. It documents commonly used methods, explains their purpose, and outlines how they are typically used within applications.

The API reference focuses on individual operations and expected behavior. End-to-end application flows are described in earlier sections of this documentation. All examples use the official JavaScript SDK (ontology-ts-sdk) and assume a basic understanding of asynchronous JavaScript.

Network & Client

Before any blockchain interaction can occur, an application must establish a connection to an Ontology node. This connection is used to submit transactions, query blockchain data, and interact with deployed smart contracts. Ontology provides public RPC endpoints, but applications may also connect to self-hosted nodes for greater control and reliability.

Creating an RPC Client

import { RestClient } from 'ontology-ts-sdk';

const rpcUrl = 'https://dappnode1.ont.io:20334';
const client = new RestClient(rpcUrl);

The RestClient instance serves as the primary communication layer between the application and the Ontology network. It does not manage keys or signing and should be treated as a stateless network client.

Wallet and Account Data

Ontology Wallet exposes limited account information to applications after user approval. This typically includes the active account address and network context required to construct transactions. Applications should not attempt to infer wallet state independently. Instead, they should rely on the wallet as the authoritative source for active account data.

Account Address

const address = 'AXxxxxxxxxxxxxxxxxxxxx';

The account address is used as the sender for transactions and contract invocations. It uniquely identifies an account on the Ontology blockchain.

Transactions

Transactions represent signed instructions that modify blockchain state. Applications construct unsigned transaction payloads using the SDK and delegate signing to Ontology Wallet.

Building a Native Token Transfer

import { TransactionBuilder } from 'ontology-ts-sdk';

const tx = TransactionBuilder.makeTransferTransaction(
  'ONT',
  fromAddress,
  toAddress,
  amount,
  gasPrice,
  gasLimit
);

This method creates an unsigned transaction object for transferring native assets such as ONT or ONG. The transaction includes sender and recipient addresses, transfer amount, and execution parameters. At this stage, the transaction is not valid for submission and must be signed by the wallet.

Submitting a Signed Transaction

const result = await client.sendRawTransaction(signedTx);

Once signed, the transaction can be submitted to the network. The RPC client returns a transaction hash and broadcast status. Final confirmation depends on network conditions and block inclusion. Applications should track transaction status and handle pending or failed states appropriately.

Smart Contract Interaction

Smart contracts on Ontology expose callable methods that applications can interact with through transactions. The SDK provides helpers to construct both read-only calls and state-changing invocations.

Invoking a Contract Method (Write)

import { TransactionBuilder } from 'ontology-ts-sdk';

const tx = TransactionBuilder.makeInvokeTransaction(
  contractAddress,
  methodName,
  params,
  fromAddress,
  gasPrice,
  gasLimit
);

This operation creates a transaction that modifies contract state. It requires wallet authorization and payment of execution fees in ONG. The exact behavior depends on the contract’s implementation.

Calling a Contract Method (Read)

const response = await client.sendRawTransaction(tx, true);

Read-only calls allow applications to query contract state without submitting a transaction or modifying blockchain data. These calls do not require signing and do not incur network fees.

ONT ID Operations

ONT ID–related actions are implemented through dedicated smart contracts. Identity operations are always executed on-chain and require wallet authorization.

Building an Identity Registration Transaction

import { OntidContract } from 'ontology-ts-sdk';

const tx = OntidContract.buildRegisterOntidTx(
  ontId,
  publicKey,
  gasPrice,
  gasLimit
);

This transaction registers a new decentralized identity on the Ontology blockchain. Like all identity actions, it must be signed by the wallet and confirmed on-chain.

Node Setup

This section describes how applications connect to Ontology blockchain nodes and configure network access for reading blockchain data and submitting transactions. Proper node setup is essential for reliable application behavior, especially in production environments. Ontology Wallet itself does not operate a node. Instead, it relies on RPC endpoints to communicate with the blockchain. Applications integrating with the wallet follow the same model and must be configured to use compatible Ontology nodes.

Connecting to an Ontology Node

Applications interact with the Ontology blockchain through RPC endpoints exposed by full nodes. These endpoints allow applications to submit signed transactions, query blockchain state, retrieve blocks, and interact with smart contracts.

Ontology provides public RPC endpoints that can be used for development and testing. For production use, applications may choose to operate their own nodes to improve reliability, performance, and control over network access.

A node connection is typically established using the Ontology SDK by creating an RPC client instance configured with the node’s endpoint URL.

import { RestClient } from 'ontology-ts-sdk';

const rpcUrl = 'https://dappnode1.ont.io:20334';
const client = new RestClient(rpcUrl);

The RPC client acts as a stateless communication layer. It does not store keys, manage accounts, or perform signing operations.

Public vs Self-Hosted Nodes

Using public nodes is suitable for development, testing, and low-volume applications. These nodes are maintained by the Ontology ecosystem and provide general access to the network. However, public nodes may have limitations such as rate limits, reduced availability guarantees, or shared resource usage.

Running a self-hosted node is recommended for applications that require:

• High availability and predictable performance
• Full control over network access and configuration
• Reduced dependency on third-party infrastructure
• Enhanced monitoring and logging

Self-hosted nodes require ongoing maintenance and should be kept up to date with protocol upgrades.

Network Configuration

Applications must ensure that all components are connected to the same network environment. Ontology supports multiple network environments, such as mainnet and testnet. Misconfigured network connections may result in failed transactions, incorrect balances, or inconsistent contract state. Applications should explicitly configure RPC endpoints and avoid relying on implicit defaults. Wallets and applications must be aligned on network selection to ensure correct transaction execution.

Node Reliability and Monitoring

Because blockchain operations are asynchronous and network-dependent, node reliability directly affects application behavior. Applications should be designed to handle temporary unavailability, slow responses, or network errors gracefully.

Recommended practices include:

• Monitoring RPC response times
• Implementing request timeouts
• Handling transient network failures
• Avoiding assumptions about immediate transaction finality

Node-level issues should be treated as expected operational conditions rather than exceptional failures.

Security Considerations

While RPC nodes do not manage private keys, they influence how applications interact with the blockchain.

Developers should ensure that:

• RPC endpoints are accessed over secure connections
• Node URLs are configured explicitly and validated
• Sensitive application logic does not depend on a single node

Ontology Wallet isolates signing operations from node communication, reducing risk exposure in the event of node compromise.

When to Use Multiple Nodes

Advanced applications may benefit from using multiple nodes for redundancy or load balancing. This approach can improve resilience and reduce the impact of node outages. In such setups, applications can dynamically select RPC endpoints based on availability or performance metrics.

Troubleshooting

Common issues you may encounter when using Ontology Wallet and how to resolve them.

Transaction Failed: Insufficient Gas

This error occurs when the account does not have enough ONG to cover the network fee required to process the transaction.

Ontology transactions require ONG as gas, even when transferring other assets such as ONT or interacting with smart contracts. If the available ONG balance is too low, the network will reject the transaction.

How to resolve:

• Check the ONG balance of the selected account
• Transfer or claim additional ONG to the account
• Retry the transaction after confirming sufficient balance

Gas fees are deducted only when a transaction is successfully submitted to the network.

Cannot Connect to Network

This issue indicates that Ontology Wallet is unable to reach the configured RPC node or network endpoint.

It may be caused by temporary network outages, incorrect node configuration, firewall restrictions, or local connectivity problems.

How to resolve:

• Verify your internet connection
• Restart the wallet application
• Check or switch the configured RPC node
• Ensure that local firewall or VPN settings are not blocking network access
• If the issue persists, try connecting to a different network endpoint if available

Invalid Address Format

This error appears when the destination address does not match the expected Ontology address format.

Common causes include truncated addresses, unsupported address types, or accidental inclusion of extra characters such as spaces.

How to resolve:

• Ensure the address was copied in full
• Confirm the address belongs to the Ontology network
• Avoid manually typing addresses when possible
• Re-copy the address directly from a trusted source

Transactions sent to invalid addresses will be rejected and not broadcast to the network.

Wallet Not Showing Expected Balance

In some cases, balances may not appear immediately after a transaction or wallet import.

This can happen due to network synchronization delays or node response issues.

How to resolve:

• Refresh the wallet or restart the application
• Wait for network confirmation
• Verify the transaction status using a blockchain explorer
• Ensure you are viewing the correct account

Balances update automatically once the network state is synchronized.

Wallet Import or Restore Failed

This issue usually occurs when recovery data is incomplete or incorrectly entered.

Recovery phrases and private keys must be provided exactly as generated.

How to resolve:

• Verify the recovery phrase order and spelling
• Ensure no extra spaces or characters are included
• Confirm the correct import method was selected
• Retry the import process carefully

If recovery data is lost or incorrect, wallet access cannot be restored