internet-court/internet-court-skill / vendored/near/near-api-js
near-api-js
VerifiedGuide 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.
| File | Kind | Size |
|---|---|---|
| LICENSE | other | 329 B |
| SKILL.md | skill md | 16.0 KB |
| references/api_patterns.md | markdown | 10.9 KB |
| references/contracts.md | markdown | 4.3 KB |
| references/key_management.md | markdown | 6.4 KB |
| references/meta_transactions.md | markdown | 5.8 KB |
| references/nep413.md | markdown | 2.7 KB |
| references/tokens_guide.md | markdown | 6.1 KB |
references/api_patterns.md
View on GitHub# near-api-js API Patterns Reference
Detailed patterns and advanced usage examples for near-api-js.
## Table of Contents
1. [Account Methods Reference](#account-methods-reference)
2. [Provider Methods Reference](#provider-methods-reference)
3. [Action Types](#action-types)
4. [Type Definitions](#type-definitions)
5. [Advanced Patterns](#advanced-patterns)
---
## Account Methods Reference
### State & Information
| Method | Description | Returns |
| --------------------------- | ----------------------------------------- | ----------------------- |
| `getState()` | Account balance, storage usage, code hash | `AccountState` |
| `getBalance()` | NEAR balance | `bigint` |
| `getBalance(token)` | FT balance for given token | `bigint` |
| `getAccessKey(publicKey)` | Single access key info | `AccessKeyView` |
| `getAccessKeyList()` | All access keys | `AccessKeyList` |
| `getContractCode()` | Deployed contract WASM | `{ code_base64, hash }` |
| `getContractState(prefix?)` | Contract key-value storage | `{ values }` |
### Transactions
| Method | Description |
| ------------------------------------------------------- | -------------------------------- |
| `signAndSendTransaction({ receiverId, actions })` | Sign and broadcast single tx |
| `signAndSendTransactions({ transactions })` | Batch multiple transactions |
| `createTransaction({ receiverId, actions, publicKey })` | Create unsigned tx |
| `createSignedTransaction({ receiverId, actions })` | Create signed tx without sending |
### Account Management
| Method | Description |
| ------------------------------------------------------------------------------- | -------------------------------------------------- |
| `addFullAccessKey(publicKey)` | Add full access key |
| `addFunctionCallAccessKey({ publicKey, contractId, methodNames?, allowance? })` | Add limited key |
| `deleteKey(publicKeyString)` | Remove access key (takes string) |
| `deleteAccount(beneficiaryAccountId)` | Delete account and send NEAR tokens to beneficiary |
| `createAccount({ newAccountId, publicKey, nearToTransfer? })` | Create named accounts and sub-accounts for them |
| `createSubAccount({ accountOrPrefix, publicKey, nearToTransfer? })` | Create `prefix.parent.near` |
### Tokens
| Method | Description |
| ----------------------------------------- | ------------------- |
| `transfer({ receiverId, amount, token })` | Transfer NEAR or FT |
---
## Provider Methods Reference
### Account Queries
```typescript
// View account
await provider.viewAccount({ accountId, blockQuery? }) // AccountView
// View access key
await provider.viewAccessKey({ accountId, publicKey, finalityQuery? })
// View all access keys
await provider.viewAccessKeyList({ accountId, finalityQuery? })
```
### Contract Queries
```typescript
// Call view method (read-only)
await provider.callFunction<ReturnType>({
contractId,
method,
args, // JSON object or Uint8Array
blockQuery?
})
// View contract code
await provider.viewContractCode({ contractId, blockQuery? })
// View contract state (raw key-values)
await provider.viewContractState({ contractId, prefix?, blockQuery? })
```
### Block & Chunk
```typescript
// View block
await provider.viewBlock({ finality: "final" });
await provider.viewBlock({ blockId: 12345 });
await provider.viewBlock({ blockId: "9eVs..." });
// View chunk
await provider.viewChunk({ chunkId: "HFks..." });
await provider.viewChunk({ blockId: 12345, shardId: 0 });
```
### Transaction
```typescript
// Send signed transaction
await provider.sendTransaction(signedTx)
// Send and wait
await provider.sendTransactionAsync({ signedTx, waitUntil: "EXECUTED_OPTIMISTIC" })
// View transaction status
await provider.viewTransactionStatus({ txHash, accountId, waitUntil? })
await provider.viewTransactionStatusWithReceipts({ txHash, accountId })
```
### Network
```typescript
await provider.viewNodeStatus()
await provider.viewGasPrice(blockId?)
await provider.viewValidators({ blockId? } | { epochId? })
await provider.getNetworkId()
```
---
## Action Types
All actions from `near-api-js`:
```typescript
import { actions } from "near-api-js"
// Transfer NEAR
actions.transfer(amount: bigint)
// Function call
actions.functionCall(
methodName: string,
args: object | Uint8Array,
gas: bigint,
deposit: bigint
)
// Account creation
actions.createAccount()
// Deploy contract
actions.deployContract(code: Uint8Array)
// Key management
actions.addFullAccessKey(publicKey: PublicKey)
actions.addFunctionAccessKey(
publicKey: PublicKey,
contractId: string,
methodNames: string[],
allowance?: bigint
)
actions.deleteKey(publicKey: PublicKey)
// Account deletion
actions.deleteAccount(beneficiaryId: string)
// Use global contract
actions.useGlobalContract(identifier: { accountId: string } | { codeHash: string | Uint8Array })
// Deploy global contract
actions.deployGlobalContract(code: Uint8Array, deployMode: 'codeHash' | 'accountId')
// Staking
actions.stake(amount: bigint, publicKey: PublicKey)
// Meta transaction
actions.signedDelegate(signedDelegateAction: SignedDelegateAction)
```
---
## Type Definitions
### Key Types
```typescript
type CurveType = "ed25519" | "secp256k1";
type KeyPairString = `${CurveType}:${string}`;
```
### Block Reference
```typescript
type BlockReference =
| { finality: "final" | "optimistic" }
| { blockId: number | string } // height or hash
| { syncCheckpoint: "genesis" | "earliest_available" };
```
### Transaction Status
```typescript
type TxExecutionStatus =
| "NONE"
| "INCLUDED"
| "INCLUDED_FINAL"
| "EXECUTED"
| "EXECUTED_OPTIMISTIC"
| "FINAL";
```
### AccountState
```typescript
interface AccountState {
balance: {
total: bigint;
usedOnStorage: bigint;
locked: bigint;
available: bigint;
};
storageUsage: number;
codeHash: string;
}
```
---
## Advanced Patterns
### Manual Transaction Signing
```typescript
import {
JsonRpcProvider,
Account,
KeyPairSigner,
actions,
KeyPairString,
} from "near-api-js";
import { NEAR } from "near-api-js/tokens";
const provider = new JsonRpcProvider({ url: "https://test.rpc.fastnear.com" });
// Signer exists separately from Account
const signer = KeyPairSigner.fromSecretKey(privateKey);
// Account without signer — just needs account ID and provider
const account = new Account(accountId, provider);
// 1. Create transaction (requires public key)
const transaction = await account.createTransaction({
receiverId: "receiver-account.testnet",
actions: [actions.transfer(NEAR.toUnits("0.1"))],
publicKey: await signer.getPublicKey(),
});
// 2. Sign transaction
const signResult = await signer.signTransaction(transaction);
// 3. Send transaction
const sendResult = await provider.sendTransaction(signResult.signedTransaction);
```
### Parallel Transactions with MultiKeySigner
```typescript
import {
Account,
actions,
JsonRpcProvider,
KeyPair,
MultiKeySigner,
KeyPairString,
} from "near-api-js";
import { NEAR } from "near-api-js/tokens";
const provider = new JsonRpcProvider({ url: "https://test.rpc.fastnear.com" });
const account = new Account(accountId, provider, privateKey);
// Create 10 keys and add them to the account on-chain
const keys: KeyPair[] = [];
const txActions: ReturnType<typeof actions.addFullAccessKey>[] = [];
for (let j = 0; j < 10; j++) {
const newKeyPair = KeyPair.fromRandom("ed25519");
keys.push(newKeyPair);
txActions.push(actions.addFullAccessKey(newKeyPair.getPublicKey()));
}
await account.signAndSendTransaction({
receiverId: accountId,
actions: txActions,
});
// Use MultiKeySigner for parallel transactions
const multiKeySigner = new MultiKeySigner(keys);
const multiAccount = new Account(accountId, provider, multiKeySigner);
// Send 100 transfers in parallel — no nonce collisions
const transfers = [...Array(100)].map(() =>
multiAccount.transfer({
token: NEAR,
amount: NEAR.toUnits("0.001"),
receiverId: "influencer.testnet",
}),
);
const results = await Promise.all(transfers);
```
### Access Key Management
```typescript
import {
Account,
JsonRpcProvider,
KeyPair,
KeyPairString,
nearToYocto,
} from "near-api-js";
import { NEAR } from "near-api-js/tokens";
const provider = new JsonRpcProvider({ url: "https://test.rpc.fastnear.com" });
// Query keys via provider
const keys = await provider.viewAccessKeyList({ accountId });
// Create Account without signer, add signer later
const account = new Account(accountId, provider, privateKey as KeyPairString);
// Query keys via account
const accessKeys = await account.getAccessKeyList();
// Generate new keys
const fullKeyPair = KeyPair.fromRandom("ed25519");
const fnKeyPair = KeyPair.fromRandom("ed25519");
// Add full access key
await account.addFullAccessKey(fullKeyPair.getPublicKey());
// Add function call access key — takes an OBJECT
await account.addFunctionCallAccessKey({
publicKey: fnKeyPair.getPublicKey(),
contractId: "example-contract.testnet",
methodNames: ["example_method"],
allowance: nearToYocto("0.25"), // put "0" for unlimited allowance
});
// Switch signer to use new key
account.setSigner(new KeyPairSigner(fullKeyPair));
// Delete keys
await account.deleteKey(fnKeyPair.getPublicKey());
await account.deleteKey(fullKeyPair.getPublicKey());
```
### Wait for Transaction Finality
```typescript
const result = await account.signAndSendTransaction({
receiverId: "contract.near",
actions: [...],
waitUntil: "FINAL", // Wait for transaction to be fully finalized on-chain
})
```
### Error Handling
```typescript
import {
AccountDoesNotExistActionError,
// and many more
} from "near-api-js/rpc-errors";
try {
await account.signAndSendTransaction({
receiverId: "unexisted_account.testnet",
actions: [...]
});
} catch (error) {
if (error instanceof AccountDoesNotExistActionError) {
console.error(
`Transaction ${error.txHash} failed because recipient ${error.accountId} does not exist!`,
);
}
}
```
### Manual Error Handling (not recommended)
```typescript
const result = await account.signAndSendTransaction({
receiverId: "unexisted_account.testnet",
actions: [...],
throwOnFailure: false // Don't throw on failure, return result object instead
});
// do manual error handling on result
console.log(result);
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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 implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |