Skip to main content

Wallet Login

The @hot-labs/near-connect library provides a secure, zero-dependency wallet connector for NEAR blockchain with a unique sandbox-based architecture.

Preview

Example

We have a working example, which you can easily get through create-near-app:

npx create-near-app@latest

Why NEAR Connect?​

Unlike traditional wallet selectors, it offers a dynamic manifest system that allows wallets to be added and updated without requiring developers to update their dependencies.

  • Secure Execution: Wallet scripts run in isolated sandboxed iframes for maximum security
  • Dynamic Wallets: Wallets are loaded from a manifest and can be updated without code changes
  • Zero Dependencies: Lightweight library with no external dependencies
  • Automatic Detection: Supports both injected wallets (extensions) and manifest-based wallets

Installation​

You can add the NEAR Connect library to your project in two ways:

Install the @hot-labs/near-connect and near-api-js packages manually:

npm install @hot-labs/near-connect near-api-js

Initializing the Connector​

Initialize the NearConnector instance in your application:

Selecting Wallets

Unlike traditional wallet selectors that bundle wallet code, NEAR Connect uses a manifest-based approach:

  1. Wallet providers register their integration scripts in a public manifest
  2. The connector dynamically loads wallet scripts when users want to connect

This architecture eliminates the need to install individual wallet packages and ensures wallet code can be updated independently from your app.

connector = new NearConnector({
  network: "testnet", // or "mainnet"
  features: {
    signMessage: true,  // Only show wallets that support message signing
    signTransaction: true,
    signInWithoutAddKey: true,
    signAndSendTransaction: true,
    signAndSendTransactions: true
  },
});

Signing In / Out​

The connector uses the Observer Pattern (pub/sub), for which we need to subscribe to the wallet:signIn" and wallet:signOut` events

Then, call the connect function to open a modal where the user can select a wallet and sign in, and disconnect to sign out

Calling Contract Method​

To call a contract method, first get the connected wallet instance using connector.wallet(), then use the wallet's signAndSendTransaction method to make a function call:

// Get the connected wallet
const wallet = await connector.wallet();

// Call a change method
const result = await wallet.signAndSendTransaction({
  receiverId: "hello.near-examples.testnet",
  actions: [
    {
      type: "FunctionCall",
      params: {
        methodName: "set_greeting",
        args: { greeting: "Hello from NEAR Connect!" },
        gas: "30000000000000", // 30 TGas
        deposit: "0", // No deposit
      },
    },
  ],
});

console.log("Transaction:", result.transaction.hash);

Calling Read-only Methods​

The near-connector does not provide a built-in way to call read-only (view) methods.

However, you can use the near-api-js package (or any of your preferred APIs) to create a JSON-RPC provider and call view methods directly:

import { JsonRpcProvider } from "near-api-js";

const provider = new JsonRpcProvider({ url: "https://test.rpc.fastnear.com" });

const greeting = await provider.callFunction(
  "hello.near-examples.testnet",
  "get_greeting",
  {}
);

Send Multiple Transactions​

You can request the user to sign and send multiple transactions in parallel through a single prompt:

const wallet = await connector.wallet();

const results = await wallet.signAndSendTransactions({
  transactions: [
    {
      receiverId: "token.near",
      actions: [
        {
          type: "FunctionCall",
          params: {
            methodName: "ft_transfer",
            args: {
              receiver_id: "alice.near",
              amount: "1000000",
            },
            gas: "30000000000000",
            deposit: "1", // 1 yoctoNEAR for security
          },
        },
      ],
    },
    {
      receiverId: "nft.near",
      actions: [
        {
          type: "FunctionCall",
          params: {
            methodName: "nft_mint",
            args: {
              token_id: "token-1",
              receiver_id: "alice.near",
            },
            gas: "30000000000000",
            deposit: "10000000000000000000000", // 0.01 NEAR
          },
        },
      ],
    },
  ],
});

console.log(`Completed ${results.length} transactions`);

Sign Messages (NEP-413)​

In NEAR, users can sign messages for authentication purposes without needing to send a transaction:

You can request the user to sign a message using the wallet's signMessage method:

const wallet = await connector.wallet();

const signature = await wallet.signMessage({
  message: "Please sign this message to authenticate",
  recipient: "your-app.near",
  nonce: Buffer.from(crypto.randomUUID()),
});

console.log("Signature:", signature.signature);
console.log("Public Key:", signature.publicKey);

// Verify the signature on your backend