Wallet Login

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

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:

Library
React Hooks

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

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

If you are using React, we recommend installing the near-connect-hooks package which provides convenient hooks for integrating NEAR Connect into your app:

npm install near-connect-hooks

Initializing the Connector

Initialize the NearConnector instance in your application:

Library
React Hooks

import { NearConnector } from '@hot-labs/near-connect';

const connector = new NearConnector({
  network: 'testnet',
  features: {
    signMessage: true,
    signTransaction: true,
  },
});

import { NearProvider } from 'near-connect-hooks';

export default function App({ Component, pageProps }) {
  return (
    <NearProvider network="testnet">
      <Component {...pageProps} />
    </NearProvider>
  );
}

Selecting Wallets

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

Wallet providers register their integration scripts in a public manifest
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

Library
React Hooks

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

connector.on('wallet:signIn', ({ accountId }) => {
  console.log('Signed in:', accountId);
});

connector.on('wallet:signOut', () => {
  console.log('Signed out');
});

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

// Sign in
await connector.connect();

// Sign out
await connector.disconnect();

The near-connect-hooks package provides a useNearWallet hook that simplifies the sign-in process:

import { useNearWallet } from 'near-connect-hooks';

function Navigation() {
  const { signIn, signOut, accountId, isConnected } = useNearWallet();

  return (
    <nav>
      {isConnected ? (
        <button onClick={signOut}>
          Disconnect {accountId}
        </button>
      ) : (
        <button onClick={signIn}>Connect Wallet</button>
      )}
    </nav>
  );
}

Calling Contract Methods

Library
React Hooks

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);

To call a contract method, you can use the callFunction method provided by the useNearWallet hook:

import { useNearWallet } from 'near-connect-hooks';

function GreetingForm() {
  const { callFunction } = useNearWallet();

  const handleSubmit = async (greeting) => {
    await callFunction({
      contractId: 'hello.near-examples.testnet',
      method: 'set_greeting',
      args: { greeting },
      gas: '30000000000000',
      deposit: '0',
    });
  };

  return <form onSubmit={handleSubmit}>...</form>;
}

Calling Read-only Methods

Library
React Hooks

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",
  {}
);

You can use the viewFunction method provided by the useNearWallet hook to call read-only methods on the contract:

import { useNearWallet } from 'near-connect-hooks';
import { useEffect, useState } from 'react';

function GreetingDisplay() {
  const { viewFunction } = useNearWallet();
  const [greeting, setGreeting] = useState('');

  useEffect(() => {
    viewFunction({ 
      contractId: 'hello.near-examples.testnet', 
      method: 'get_greeting' 
    }).then(setGreeting);
  }, [viewFunction]);

  return <p>{greeting}</p>;
}

Get Balance

Library
React Hooks

The near-connector does not provide a built-in way to get the account balance.However, you can use the near-api-js package (or any of your preferred APIs) to create a JSON-RPC provider and query the account balance directly:

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

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

const account = await provider.viewAccount({ 
  accountId: "hello.near-examples.testnet" 
});

console.log("Balance:", account.amount);

You can use the getBalance method provided by the useNearWallet hook to get the user’s balance:

import { useNearWallet } from 'near-connect-hooks';
import { yoctoToNear } from 'near-api-js';

function BalanceDisplay() {
  const { getBalance } = useNearWallet();
  const [balance, setBalance] = useState('');

  useEffect(() => {
    getBalance().then((b) => {
      setBalance(yoctoToNear(b.available, 2));
    });
  }, [getBalance]);

  return <p>Balance: {balance} NEAR</p>;
}

Send Multiple Transactions

Library
React Hooks

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`);

You can use the signAndSendTransactions method provided by the useNearWallet hook to send multiple transactions in a single request:

import { useNearWallet } from 'near-connect-hooks';

function BatchTransactions() {
  const { signAndSendTransactions } = useNearWallet();

  const handleBatch = async () => {
    const results = await signAndSendTransactions({
      transactions: [
        {
          receiverId: "token.near",
          actions: [
            {
              type: "FunctionCall",
              params: {
                methodName: "ft_transfer",
                args: {
                  receiver_id: "alice.near",
                  amount: "1000000",
                },
                gas: "30000000000000",
                deposit: "1",
              },
            },
          ],
        },
        {
          receiverId: "nft.near",
          actions: [
            {
              type: "FunctionCall",
              params: {
                methodName: "nft_mint",
                args: {
                  token_id: "token-1",
                  receiver_id: "alice.near",
                },
                gas: "30000000000000",
                deposit: "10000000000000000000000",
              },
            },
          ],
        },
      ],
    });
    
    console.log(`Completed ${results.length} transactions`);
  };

  return <button onClick={handleBatch}>Send Batch</button>;
}

Sign Messages (NEP-413)

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

Library
React Hooks

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

You can use the signNEP413Message method provided by the useNearWallet hook to request the user to sign a message:

import { useNearWallet } from 'near-connect-hooks';

function MessageSigner() {
  const { signNEP413Message } = useNearWallet();

  const handleSign = async () => {
    const signature = await signNEP413Message({
      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);
  };

  return <button onClick={handleSign}>Sign Message</button>;
}

Message signing is supported by wallets that implement NEP-413, including Meteor Wallet, Here Wallet, MyNearWallet, and others.

For applications that need to onboard non-crypto users, consider using social login providers:

Privy

Web3Auth

Alternative social login with Web3Auth integration

Both Privy and Web3Auth automatically create NEAR wallets for users upon login, providing a seamless onboarding experience.

Getting Started

Protocol

Smart Contracts

Web3 Applications

AI and Agents

Chain Abstraction

Primitives

Data Infrastructure

Why NEAR Connect?

Secure Execution

Dynamic Wallets

Zero Dependencies

Automatic Detection

Installation

Initializing the Connector

Signing In / Out

Calling Contract Methods

Calling Read-only Methods

Get Balance

Send Multiple Transactions

Sign Messages (NEP-413)

Privy

Web3Auth

Build docs developers (and LLMs) love

Getting Started

Protocol

Smart Contracts

Web3 Applications

AI and Agents

Chain Abstraction

Primitives

Data Infrastructure

​Why NEAR Connect?

Secure Execution

Dynamic Wallets

Zero Dependencies

Automatic Detection

​Installation

​Initializing the Connector

​Signing In / Out

​Calling Contract Methods

​Calling Read-only Methods

​Get Balance

​Send Multiple Transactions

​Sign Messages (NEP-413)

​Alternative: Social Login

Privy

Web3Auth

Build docs developers (and LLMs) love

Why NEAR Connect?

Installation

Initializing the Connector

Signing In / Out

Calling Contract Methods

Calling Read-only Methods

Get Balance

Send Multiple Transactions

Sign Messages (NEP-413)

Alternative: Social Login