Neo N3 WalletKit

A framework-independent TypeScript package for connecting frontend applications to Neo N3 wallets and calling smart contracts.

Supported wallets:

• WalletConnect
• NeoLine
• OneGate

The same contract API works with every supported wallet.

Install

npm install neo-n3-walletkit

Choose A Wallet

| Wallet | Requirements | Initialize with | | --- | --- | --- | | WalletConnect | WalletConnect project ID and application metadata | WalletKit.init() | | NeoLine | NeoLine N3 browser extension installed and unlocked | WalletKit.initNeoLine() | | OneGate | Open the dApp inside a OneGate browser that supports NEP-21 | WalletKit.initOneGate() |

All wallets default to neo3:testnet. The network selected in the wallet must match the network configured in WalletKit.

WalletConnect Setup

WalletConnect requires:

• A project ID from WalletConnect Cloud
• Application metadata
• A wallet that supports the requested Neo N3 methods

Create a shared wallet module:

// wallet.ts
import { WalletKit } from "neo-n3-walletkit";

export const walletKit = await WalletKit.init({
  projectId: "your-walletconnect-project-id",
  relayUrl: "wss://relay.walletconnect.com",
  metadata: {
    name: "My Neo App",
    description: "My Neo N3 application",
    url: window.location.origin,
    icons: ["/icon.png"]
  },
  network: "neo3:testnet"
});

Connect the wallet:

import { walletKit } from "./wallet";

await walletKit.connect();

For a custom QR code or link flow, use createConnection() instead of connect(). This does not open Neon automatically:

const { uri, approval } = await walletKit.createConnection();

if (uri) {
  showQrCode(uri); // Render this WalletConnect URI as a QR code.
}

await approval();

You can also show a Neon link next to the QR code:

const { uri, approval } = await walletKit.createConnection();

if (!uri) {
  await approval();
} else {
  const neonUrl = new URL("https://neon.coz.io/connect");
  neonUrl.searchParams.set("uri", uri);

  console.log("WalletConnect URI:", uri);
  console.log("Open in Neon:", neonUrl.toString());

  // Example UI:
  // renderQrCode(uri);
  // renderCopyButton(uri);
  // renderLink("Open Neon", neonUrl.toString());

  await approval(); // Resolves after the user approves in Neon.
}

Use the raw uri for the QR code. Use the neonUrl for a clickable link or button.

NeoLine Setup

NeoLine requires:

• The NeoLine N3 browser extension
• The extension to be unlocked
• NeoLine to use the same network as WalletKit

Create a shared wallet module:

// wallet.ts
import { WalletKit } from "neo-n3-walletkit";

export const walletKit = await WalletKit.initNeoLine({
  network: "neo3:testnet"
});

Connect the wallet:

import { walletKit } from "./wallet";

await walletKit.connect();

OneGate Setup

OneGate requires:

• The dApp to run inside a OneGate browser with NEP-21 support
• OneGate to use the same network as WalletKit

Create a shared wallet module:

// wallet.ts
import { WalletKit } from "neo-n3-walletkit";

export const walletKit = await WalletKit.initOneGate({
  network: "neo3:testnet"
});

Connect the wallet:

import { walletKit } from "./wallet";

await walletKit.connect();

WalletKit discovers OneGate through the NEP-21 provider events.

Call A Smart Contract

After initializing and connecting any supported wallet, create a contract helper:

import { walletKit } from "./wallet";

const contract = walletKit.contract(
  "0x010101c0775af568185025b0ce43cfaa9b990a2a"
);

Call a read-only method:

const result = await contract.testInvokeFirst<string>("getTry", [
  { type: "String", value: "my-answer" }
]);

Call a method that creates a transaction:

const account = walletKit.account;

if (!account) {
  throw new Error("Connect a wallet first");
}

const txid = await contract.invoke("submitAnswer", [
  { type: "Address", value: account.address },
  { type: "String", value: "puzzle-1" },
  { type: "String", value: "my-answer" }
]);

invoke() requests a signed transaction and returns its transaction ID. testInvoke() and testInvokeFirst() do not persist blockchain changes.

WalletKit automatically adds the connected account as a CalledByEntry signer unless the call provides its own signers.

Connection State

console.log(walletKit.isConnected);
console.log(walletKit.account?.address);
console.log(walletKit.account?.scriptHash);

const unsubscribe = walletKit.onSessionChange(session => {
  console.log("Wallet session changed", session);
});

await walletKit.disconnect();
unsubscribe();

For NeoLine and OneGate, disconnect() clears WalletKit's local session. Disconnect the dApp inside the wallet to fully revoke its connection.

Provider-Specific Methods

The active wallet adapter is available through walletKit.wallet.

import { NeoLineAdapter } from "neo-n3-walletkit";

const neoLine = walletKit.wallet as NeoLineAdapter;
const balances = await neoLine.provider.getBalance({
  address: walletKit.account!.address
});

import { OneGateAdapter } from "neo-n3-walletkit";

const oneGate = walletKit.wallet as OneGateAdapter;
const balance = await oneGate.provider.getBalance(
  "0xd2a4cff31913016155e38e474a2c06d08be276cf",
  `0x${walletKit.account!.scriptHash}`
);

Provider-specific adapters and types can also be imported from neo-n3-walletkit/neoline, neo-n3-walletkit/onegate, and neo-n3-walletkit/wallet-connect.

Framework Usage

WalletKit has no Angular, React, Vue, Svelte, or RxJS dependency. Export one initialized instance from wallet.ts, then import or wrap it using your framework's normal state-management tools.

For tiny Angular and React examples in this repository, see ../Angular and ../React.