Skip to content

internet-court/internet-court-skill / vendored/near/near-api-js

near-api-js

Verified

Guide for developing with near-api-js v7 - the JavaScript/TypeScript library for NEAR blockchain interaction. Use when: (1) building apps that interact with NEAR blockchain, (2) creating/signing transactions, (3) calling smart contracts, (4) managing accounts and keys, (5) working with NEAR RPC API, (6) handling FT/NFT tokens on NEAR, (7) using NEAR cryptographic operations (KeyPair, signing), (8) converting between NEAR units (yocto, gas), (9) gasless/meta transactions with relayers, (10) NEP-413 message signing for authentication, (11) storage deposit management for FT contracts. Triggers on any NEAR blockchain development tasks.

FileKindSize
LICENSEother329 B
SKILL.mdskill md16.0 KB
references/api_patterns.mdmarkdown10.9 KB
references/contracts.mdmarkdown4.3 KB
references/key_management.mdmarkdown6.4 KB
references/meta_transactions.mdmarkdown5.8 KB
references/nep413.mdmarkdown2.7 KB
references/tokens_guide.mdmarkdown6.1 KB

references/contracts.md

View on GitHub
# Contracts

Contract usage with ABI.

## Table of Contents

1. [Contract with ABI](#contract-with-abi)
2. [Contract without ABI](#contract-without-abi)

---

## Contract with ABI

### Basic Usage

```typescript
import {
  nearToYocto,
  Account,
  Contract,
  JsonRpcProvider,
  KeyPairString,
} from "near-api-js";

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

// ABI definition requires "as const" (const assertions), otherwise types won't be inferred correctly
const abi = {
  schema_version: "0.4.0",
  metadata: {},
  body: {
    functions: [
      {
        name: "add_message",
        kind: "call",
        modifiers: ["payable"],
        params: {
          serialization_type: "json",
          args: [
            {
              name: "text",
              type_schema: {
                type: "string",
              },
            },
          ],
        },
      },
      {
        name: "total_messages",
        kind: "view",
        result: {
          serialization_type: "json",
          type_schema: {
            type: "integer",
            format: "uint32",
            minimum: 0.0,
          },
        },
      },
    ],
    root_schema: {},
  },
} as const satisfies AbiRoot;

const contract = new Contract({
  contractId: "guestbook.near-examples.testnet",
  provider: provider,
  abi: abi,
});

// the interface of view and call methods are fully inferred from the ABI, including argument and return types
const total = await contract.view.total_messages();
await contract.call.add_message({
  account: account,
  args: { text: "Hello, NEAR!" },
  deposit: nearToYocto("0.1"),
});
```

### ABI Definition

ABI definitions require `as const` for proper type inference:

```typescript
// This is WRONG, abi won't be inferred
const abi = {
  schema_version: "0.4.0",
  metadata: {},
  body: {
    functions: [
      {
        name: "add_message",
        kind: "call",
        modifiers: ["payable"],
        params: {
          serialization_type: "json",
          args: [
            {
              name: "text",
              type_schema: { type: "string" },
            },
          ],
        },
      },
      {
        name: "total_messages",
        kind: "view",
        result: {
          serialization_type: "json",
          type_schema: { type: "integer", format: "uint32", minimum: 0.0 },
        },
      },
    ],
    root_schema: {},
  },
};

// This is also WRONG, abi won't be inferred:
import abi from "abi.json" assert { type: "json" };

// This is CORRECT, abi will be properly inferred:
import { AbiRoot } from "near-api-js";

const abi = {
  schema_version: "0.4.0",
  metadata: {},
  body: {
    functions: [
      {
        name: "add_message",
        kind: "call",
        modifiers: ["payable"],
        params: {
          serialization_type: "json",
          args: [
            {
              name: "text",
              type_schema: { type: "string" },
            },
          ],
        },
      },
      {
        name: "total_messages",
        kind: "view",
        result: {
          serialization_type: "json",
          type_schema: { type: "integer", format: "uint32", minimum: 0.0 },
        },
      },
    ],
    root_schema: {},
  },
} as const satisfies AbiRoot;
```

### View vs Call Methods

```typescript
// View methods: free, read-only, no account needed
const value = await contract.view.get_data();

// Call methods: require account, may require deposit/gas
await contract.call.set_data({
  account: account, // required — who signs the transaction
  args: { key: "value" }, // method arguments
  deposit: nearToYocto("0.1"), // optional — attached deposit
  gas: teraToGas("30"), // optional — gas limit
});
```

---

## Contract without ABI

When no ABI is available, use generics for type safety:

```typescript
import { Contract } from "near-api-js";

const contract = new Contract({
  contractId: "guestbook.near-examples.testnet",
  provider: provider,
});

// View methods — specify return type with generic
const total = await contract.view.total_messages<number>({ args: {} });

// Call methods — specify return type with generic
await contract.call.add_message<void>({
  account: account,
  args: { text: "Hello, NEAR!" },
  deposit: nearToYocto("0.1"),
});
```
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall