near-kit

near-kit

直感的で fetch のように使える API を備えた、NEAR Protocol 用の TypeScript ライブラリです。

クイックスタート

import { Near } from "near-kit";

// Read-only (no key needed)
const near = new Near({ network: "testnet" });
const data = await near.view("contract.near", "get_data", { key: "value" });

// With signing capability
const near = new Near({
  network: "testnet",
  privateKey: "ed25519:...",
  defaultSignerId: "alice.testnet",
});
await near.call("contract.near", "method", { arg: "value" });
await near.send("bob.testnet", "1 NEAR");

インポート早見表

// Core
import { Near } from "near-kit";

// Keys
import { generateKey, parseSeedPhrase, generateSeedPhrase } from "near-kit";
import { RotatingKeyStore, InMemoryKeyStore } from "near-kit";
import { FileKeyStore } from "near-kit/keys/file";
import { NativeKeyStore } from "near-kit/keys/native";

// Wallet adapters
import { fromHotConnect, fromWalletSelector } from "near-kit";

// NEP-413 verification
import { verifyNep413Signature } from "near-kit";

// Utilities
import { Amount, Gas, isValidAccountId } from "near-kit";

基本操作

ビューメソッド（読み取り専用、無料）

const result = await near.view("contract.near", "get_data", { key: "value" });
const balance = await near.getBalance("alice.near");
const exists = await near.accountExists("alice.near");

コールメソッド（署名が必要）

await near.call(
  "contract.near",
  "method",
  { arg: "value" },
  { gas: "30 Tgas", attachedDeposit: "1 NEAR" },
);

NEAR トークンの送信

await near.send("bob.near", "5 NEAR");

型安全なコントラクト

import type { Contract } from "near-kit";

type MyContract = Contract<{
  view: {
    get_balance: (args: { account_id: string }) => Promise<string>;
  };
  call: {
    transfer: (args: { to: string; amount: string }) => Promise<void>;
  };
}>;

const contract = near.contract<MyContract>("token.near");

// View (no options needed)
await contract.view.get_balance({ account_id: "alice.near" });

// Call (options as second arg)
await contract.call.transfer(
  { to: "bob.near", amount: "10" },
  { attachedDeposit: "1 yocto" },
);

型指定なしのコントラクトプロキシ：

const guestbook = near.contract("guestbook.near-examples.testnet");

const total = await guestbook.view.total_messages();
const result = await guestbook.call.add_message(
  { text: "Hello!" },
  { gas: "30 Tgas" },
);

トランザクションビルダー

複数のアクションを1つのアトミックなトランザクションにまとめます：

const result = await near
  .transaction("alice.near")
  .functionCall("counter.near", "increment", {}, { gas: "30 Tgas" })
  .transfer("counter.near", "0.001 NEAR")
  .send();

すべてのトランザクションアクションとメタトランザクションについては、references/transactions.mdを参照してください

設定

バックエンド／スクリプト

// Direct private key
const near = new Near({
  network: "testnet",
  privateKey: "ed25519:...",
  defaultSignerId: "alice.testnet",
});

// File-based keystore
import { FileKeyStore } from "near-kit/keys/file";
const near = new Near({
  network: "testnet",
  keyStore: new FileKeyStore("~/.near-credentials", "testnet"),
});

// High-throughput with rotating keys
import { RotatingKeyStore } from "near-kit";
const near = new Near({
  network: "mainnet",
  keyStore: new RotatingKeyStore({
    "bot.near": ["ed25519:key1...", "ed25519:key2...", "ed25519:key3..."],
  }),
});

すべてのキーストアとユーティリティについては、references/keys-and-testing.mdを参照してください

ブラウザーウォレット

import { NearConnector } from "@hot-labs/near-connect";
import { Near, fromHotConnect } from "near-kit";

const connector = new NearConnector({ network: "mainnet" });

connector.on("wallet:signIn", async (event) => {
  const near = new Near({
    network: "mainnet",
    wallet: fromHotConnect(connector),
  });

  await near.call("contract.near", "method", { arg: "value" });
});

connector.connect();

HOT Connect と Wallet Selector の統合については、references/wallets.mdを参照してください

React バインディング（@near-kit/react）

import { NearProvider, useNear, useView, useCall } from "@near-kit/react";

function App() {
  return (
    <NearProvider config={{ network: "testnet" }}>
      <Counter />
    </NearProvider>
  );
}

function Counter() {
  const { data: count, isLoading } = useView<{}, number>({
    contractId: "counter.testnet",
    method: "get_count",
  });

  const { mutate: increment, isPending } = useCall({
    contractId: "counter.testnet",
    method: "increment",
  });

  if (isLoading) return <div>Loading...</div>;
  return (
    <button onClick={() => increment({})} disabled={isPending}>
      Count: {count}
    </button>
  );
}

すべての React フック、React Query／SWR の統合、SSR のパターンについては、references/react.mdを参照してください

Sandbox を使用したテスト

import { Near } from "near-kit";
import { Sandbox } from "near-kit/sandbox";

const sandbox = await Sandbox.start();
const near = new Near({ network: sandbox });

const testAccount = `test-${Date.now()}.${sandbox.rootAccount.id}`;
await near
  .transaction(sandbox.rootAccount.id)
  .createAccount(testAccount)
  .transfer(testAccount, "10 NEAR")
  .send();

await sandbox.stop();

Sandbox のパターンと Vitest の統合については、references/keys-and-testing.mdを参照してください

エラー処理

import {
  InsufficientBalanceError,
  FunctionCallError,
  NetworkError,
  TimeoutError,
} from "near-kit";

try {
  await near.call("contract.near", "method", {});
} catch (error) {
  if (error instanceof InsufficientBalanceError) {
    console.log(`Need ${error.required}, have ${error.available}`);
  } else if (error instanceof FunctionCallError) {
    console.log(`Panic: ${error.panic}`, `Logs: ${error.logs}`);
  }
}

単位のフォーマット

すべての金額は人が読みやすい形式で指定できます：

"10 NEAR"; // 10 NEAR
"10"; // 10 NEAR
10; // 10 NEAR
("30 Tgas"); // 30 trillion gas units

プログラムによるフォーマット：

import { Amount, Gas } from "near-kit";

Amount.NEAR(0.1);
Amount.yocto(1000n);
Amount.parse("5 NEAR");
Gas.parse("30 Tgas");

キーユーティリティ

import {
  generateKey,
  generateSeedPhrase,
  parseSeedPhrase,
  isValidAccountId,
} from "near-kit";

// Generate new keypair
const key = generateKey();
// key.publicKey, key.secretKey

// generateSeedPhrase() returns a string (just the phrase)
const seedPhrase = generateSeedPhrase();
// "word1 word2 word3 ... word12"

// parseSeedPhrase() returns a KeyPair-like object
const keyPair = parseSeedPhrase("word1 word2 ... word12");
// keyPair.publicKey, keyPair.secretKey

// Validation
isValidAccountId("alice.near"); // true

NEP-413 の検証

import { Near, verifyNep413Signature } from "near-kit";

const near = new Near({ network: "testnet" });

const isValid = await verifyNep413Signature(
  signedMessage,
  { message: "log me in", recipient: "myapp.com", nonce: challengeBuffer },
  { near, maxAge: Infinity },
);

リファレンス

トピックごとの詳細なドキュメントについては、以下を参照してください：

• React バインディング - プロバイダー、フック、React Query／SWR、SSR／Next.js
• ウォレット統合 - HOT Connect、Wallet Selector、汎用的なパターン
• トランザクションビルダー - すべてのアクション、メタトランザクション（NEP-366）
• キーとテスト - キーストア、ユーティリティ、Sandbox、NEP-413 署名

上流プロジェクトと来歴

• near-kit はコミュニティライブラリです — r-near/near-kit（npm：near-kit、@near-kit/react、現在の ^0.20.x）
• 公式ドキュメントでは near-kit を扱っていません。ここに記載された正確なシグネチャに依存する前に、新しい API をリポジトリの README で確認してください
• near-api-js の基本情報と RPC の詳細については、公式ドキュメントを参照してください：docs.near.org/tools/near-api
• 新しいアプリでは Wallet Selector の代わりにnear-connect connectorを使用してください。詳しくはreferences/wallets.mdを参照してください