diff --git a/packages/near-sdk-js/lib/api.d.ts b/packages/near-sdk-js/lib/api.d.ts
index 5a5f9274a..4a59a43ff 100644
--- a/packages/near-sdk-js/lib/api.d.ts
+++ b/packages/near-sdk-js/lib/api.d.ts
@@ -1,65 +1,172 @@
+/**
+ * Blockchain-specific methods available to the smart contract.
+ * @module near
+ * */
 import { NearAmount, PromiseIndex } from "./utils";
 import { GasWeight } from "./types";
 /**
  * Logs parameters in the NEAR WASM virtual machine.
+ * This message is stored on chain.
  *
  * @param params - Parameters to log.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.log("hello world"); // -> "hello world"
+ * near.log("key", 2024); // -> "key 2024"
+ * near.log("user", { id: 1, name: "Test" }); // `user {"id": 1, "name": "Test"}`
+ * near.log("text", undefined, "user", { id: 1, name: "Test" }); // `text undefined user {"id": 1, "name": "Test"}`
+ * ```
  */
 export declare function log(...params: unknown[]): void;
 /**
  * Returns the account ID of the account that signed the transaction.
  * Can only be called in a call or initialize function.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.signerAccountId(); // -> "test.near"
+ * ```
  */
 export declare function signerAccountId(): string;
 /**
  * Returns the public key of the account that signed the transaction.
  * Can only be called in a call or initialize function.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.signerAccountPk(); // -> [56, 91, 91, 85, 17, 172, 223, ...]
+ * ```
  */
 export declare function signerAccountPk(): Uint8Array;
 /**
  * Returns the account ID of the account that called the function.
  * Can only be called in a call or initialize function.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.predecessorAccountId(); // -> "caller.near"
+ * ```
  */
 export declare function predecessorAccountId(): string;
 /**
  * Returns the account ID of the current contract - the contract that is being executed.
+ * The id of the account that owns the current contract.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.currentAccountId(); // -> "example.near"
+ * ```
  */
 export declare function currentAccountId(): string;
 /**
  * Returns the current block index.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.blockIndex(); // -> bigint("681923959192")
+ * ```
  */
 export declare function blockIndex(): bigint;
 /**
  * Returns the current block height.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.blockHeight(); // -> bigint("681923959192")
+ * ```
  */
 export declare function blockHeight(): bigint;
 /**
- * Returns the current block timestamp.
+ * Returns the current block timestamp, number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.blockTimestamp(); // -> bigint("1704124941241242141")
+ * ```
  */
 export declare function blockTimestamp(): bigint;
 /**
  * Returns the current epoch height.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.epochHeight(); // -> bigint("185829414")
+ * ```
  */
 export declare function epochHeight(): bigint;
 /**
  * Returns the amount of NEAR attached to this function call.
  * Can only be called in payable functions.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.attachedDeposit(); // -> bigint("210000000000000")
+ * ```
  */
 export declare function attachedDeposit(): bigint;
 /**
  * Returns the amount of Gas that was attached to this function call.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.prepaidGas(); // -> bigint("30000000000000")
+ * ```
  */
 export declare function prepaidGas(): bigint;
 /**
  * Returns the amount of Gas that has been used by this function call until now.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.usedGas(); // -> bigint("5003005000000")
+ * ```
  */
 export declare function usedGas(): bigint;
 /**
- * Returns the current account's account balance.
+ * Returns the current account's account balance. This includes the attached_deposit that was attached to the transaction.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.accountBalance(); // -> bigint("10500000210000000")
+ * ```
  */
 export declare function accountBalance(): bigint;
 /**
- * Returns the current account's locked balance.
+ * Returns the current account's locked balance. The balance locked for potential validator staking.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.accountLockedBalance(); // -> bigint("10500000210000000")
+ * ```
  */
 export declare function accountLockedBalance(): bigint;
 /**
@@ -72,6 +179,15 @@ export declare function storageReadRaw(key: Uint8Array): Uint8Array | null;
  * Reads the utf-8 string value from NEAR storage that is stored under the provided key.
  *
  * @param key - The utf-8 string key to read from storage.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.storageRead("key"); // -> null
+ * near.storageWrite("key", "value");
+ * near.storageRead("key"); // -> "value"
+ * ```
  */
 export declare function storageRead(key: string): string | null;
 /**
@@ -84,6 +200,15 @@ export declare function storageHasKeyRaw(key: Uint8Array): boolean;
  * Checks for the existence of a value under the provided utf-8 string key in NEAR storage.
  *
  * @param key - The utf-8 string key to check for in storage.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.storageHasKey("key"); // -> false
+ * near.storageWrite("key", "value");
+ * near.storageHasKey("key"); // -> true
+ * ```
  */
 export declare function storageHasKey(key: string): boolean;
 /**
@@ -92,10 +217,31 @@ export declare function storageHasKey(key: string): boolean;
 export declare function storageGetEvictedRaw(): Uint8Array;
 /**
  * Get the last written or removed value from NEAR storage as utf-8 string.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.storageWrite("key", "value111");
+ * near.storageGetEvicted(); // -> "value111"
+ *
+ * near.storageWrite("key2", "value222");
+ * near.storageGetEvicted(); // -> "value222"
+ *
+ * near.storageRemove("key");
+ * near.storageGetEvicted(); // -> "value111"
+ * ```
  */
 export declare function storageGetEvicted(): string;
 /**
  * Returns the current accounts NEAR storage usage.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.storageUsage(); // -> bigint("73841284183493")
+ * ```
  */
 export declare function storageUsage(): bigint;
 /**
@@ -110,6 +256,15 @@ export declare function storageWriteRaw(key: Uint8Array, value: Uint8Array): boo
  *
  * @param key - The utf-8 string key under which to store the value.
  * @param value - The utf-8 string value to store.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.storageRead("key"); // -> null
+ * near.storageWrite("key", "value");
+ * near.storageRead("key"); // -> "value"
+ * ```
  */
 export declare function storageWrite(key: string, value: string): boolean;
 /**
@@ -122,18 +277,50 @@ export declare function storageRemoveRaw(key: Uint8Array): boolean;
  * Removes the value of the provided utf-8 string key from NEAR storage.
  *
  * @param key - The utf-8 string key to be removed.
+ *
+ * @returns Removes the value stored under the given key. If key-value existed returns true, otherwise false.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.storageRemove("key"); // -> false
+ * near.storageWrite("key", "value");
+ * near.storageRemove("key"); // -> true
+ * ```
  */
 export declare function storageRemove(key: string): boolean;
 /**
  * Returns the cost of storing 0 Byte on NEAR storage.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.storageByteCost(); // -> bigint("10000000000000000000")
+ * ```
  */
 export declare function storageByteCost(): bigint;
 /**
- * Returns the arguments passed to the current smart contract call.
+ * Returns the arguments passed to the current smart contract call as bytes.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.inputRaw(); // -> Uint8Array([0, 128, 255, 15, ...])
+ * ```
  */
 export declare function inputRaw(): Uint8Array;
 /**
  * Returns the arguments passed to the current smart contract call as utf-8 string.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.input(); // -> `{"key": "value"}`
+ * ```
  */
 export declare function input(): string;
 /**
@@ -144,12 +331,32 @@ export declare function input(): string;
 export declare function valueReturnRaw(value: Uint8Array): void;
 /**
  * Returns the utf-8 string value from the NEAR WASM virtual machine.
+ * Sets the utf-8 string as the return value of this function.
  *
  * @param value - The utf-8 string value to return.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const user = {
+ *  id: 128,
+ *  name: "Test",
+ *  key: "value"
+ * };
+ * near.valueReturn(JSON.stringify(user));
+ * ```
  */
 export declare function valueReturn(value: string): void;
 /**
- * Returns a random string of bytes.
+ * Returns a random string of bytes. This returns a 32 byte hash.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.randomSeed(); // -> [2, 4, 98, 124, 0, 224, ...]
+ * ```
  */
 export declare function randomSeed(): Uint8Array;
 /**
@@ -170,6 +377,19 @@ export declare function promiseCreateRaw(accountId: string, methodName: string,
  * @param args - The utf-8 string arguments to call the method with.
  * @param amount - The amount of NEAR attached to the call.
  * @param gas - The amount of Gas attached to the call.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseCreate(
+ *  "contract.near",
+ *  "increase",
+ *  `{"value": 5}`,
+ *  bigint("0"),
+ *  bigint("30000000000000")
+ * );
+ * ```
  */
 export declare function promiseCreate(accountId: string, methodName: string, args: string, amount: NearAmount, gas: NearAmount): PromiseIndex;
 /**
@@ -192,18 +412,60 @@ export declare function promiseThenRaw(promiseIndex: PromiseIndex, accountId: st
  * @param args - The utf-8 string arguments to call the method with.
  * @param amount - The amount of NEAR to attach to the call.
  * @param gas - The amount of Gas to attach to the call.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseCreate(
+ *  "contract.near",
+ *  "increase",
+ *  `{"value": 5}`,
+ *  bigint("0"),
+ *  bigint("30000000000000")
+ * );
+ *
+ * const chainedPromise = near.promiseThen(
+ *  promise,
+ *  "contract2.near",
+ *  "set_greeting",
+ *  `{"text": "Hello, world!"}`,
+ *  bigint("1000000000000"),
+ *  bigint("30000000000000")
+ * );
+ * ```
  */
 export declare function promiseThen(promiseIndex: PromiseIndex, accountId: string, methodName: string, args: string, amount: NearAmount, gas: NearAmount): PromiseIndex;
 /**
  * Join an arbitrary array of NEAR promises.
  *
  * @param promiseIndexes - An arbitrary array of NEAR promise indexes to join.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise1 = near.promiseBatchCreate("receiver1.near");
+ * near.promiseBatchActionTransfer(promise1, bigint("10000000000000000"));
+ *
+ * const promise2 = near.promiseBatchCreate("receiver2.near");
+ * near.promiseBatchActionTransfer(promise2, bigint("30500050000000000"));
+ *
+ * const promise = near.promiseAnd(promise1, promise2);
+ * ```
  */
 export declare function promiseAnd(...promiseIndexes: PromiseIndex[]): PromiseIndex;
 /**
  * Create a NEAR promise which will have multiple promise actions inside.
  *
  * @param accountId - The account ID of the target contract.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("receiver.near");
+ * ```
  */
 export declare function promiseBatchCreate(accountId: string): PromiseIndex;
 /**
@@ -211,12 +473,32 @@ export declare function promiseBatchCreate(accountId: string): PromiseIndex;
  *
  * @param promiseIndex - The NEAR promise index of the batch.
  * @param accountId - The account ID of the target contract.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise1 = near.promiseBatchCreate("receiver1.near");
+ * near.promiseBatchActionTransfer(promise1, bigint("10000000000000000"));
+ *
+ * const promise2 = near.promiseBatchThen(promise1, "receiver2.near");
+ * near.promiseBatchActionTransfer(promise2, bigint("2500000000000000000"));
+ * ```
  */
 export declare function promiseBatchThen(promiseIndex: PromiseIndex, accountId: string): PromiseIndex;
 /**
  * Attach a create account promise action to the NEAR promise index with the provided promise index.
  *
  * @param promiseIndex - The index of the promise to attach a create account action to.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("receiver.near");
+ *
+ * near.promiseBatchActionCreateAccount(promise);
+ * ```
  */
 export declare function promiseBatchActionCreateAccount(promiseIndex: PromiseIndex): void;
 /**
@@ -224,6 +506,15 @@ export declare function promiseBatchActionCreateAccount(promiseIndex: PromiseInd
  *
  * @param promiseIndex - The index of the promise to attach a deploy contract action to.
  * @param code - The WASM byte code of the contract to be deployed.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("contract.near");
+ *
+ * near.promiseBatchActionDeployContract(promise, [21, 24, 9, 6, 53, 229, ...]);
+ * ```
  */
 export declare function promiseBatchActionDeployContract(promiseIndex: PromiseIndex, code: Uint8Array): void;
 /**
@@ -244,6 +535,21 @@ export declare function promiseBatchActionFunctionCallRaw(promiseIndex: PromiseI
  * @param args - The utf-8 string arguments to call the method with.
  * @param amount - The amount of NEAR to attach to the call.
  * @param gas - The amount of Gas to attach to the call.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("counter.near");
+ *
+ * near.promiseBatchActionFunctionCall(
+ *  promise,
+ *  "increase",
+ *  `{"value": 5}`,
+ *  bigint("0"),
+ *  bigint("30000000000000")
+ * );
+ * ```
  */
 export declare function promiseBatchActionFunctionCall(promiseIndex: PromiseIndex, methodName: string, args: string, amount: NearAmount, gas: NearAmount): void;
 /**
@@ -251,6 +557,14 @@ export declare function promiseBatchActionFunctionCall(promiseIndex: PromiseInde
  *
  * @param promiseIndex - The index of the promise to attach a transfer action to.
  * @param amount - The amount of NEAR to transfer.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("receiver.near");
+ * near.promiseBatchActionTransfer(promise, bigint("10000000000000000"));
+ * ```
  */
 export declare function promiseBatchActionTransfer(promiseIndex: PromiseIndex, amount: NearAmount): void;
 /**
@@ -259,6 +573,19 @@ export declare function promiseBatchActionTransfer(promiseIndex: PromiseIndex, a
  * @param promiseIndex - The index of the promise to attach a stake action to.
  * @param amount - The amount of NEAR to stake.
  * @param publicKey - The public key with which to stake.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("contract.near");
+ *
+ * near.promiseBatchActionStake(
+ *  promise,
+ *  bigint("59319390502334010"),
+ *  [2, 4, 59, 12, 48, 91, ...]
+ * );
+ * ```
  */
 export declare function promiseBatchActionStake(promiseIndex: PromiseIndex, amount: NearAmount, publicKey: Uint8Array): void;
 /**
@@ -267,6 +594,21 @@ export declare function promiseBatchActionStake(promiseIndex: PromiseIndex, amou
  * @param promiseIndex - The index of the promise to attach a add full access key action to.
  * @param publicKey - The public key to add as a full access key.
  * @param nonce - The nonce to use.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("receiver.near");
+ *
+ * near.promiseBatchActionCreateAccount(promise);
+ *
+ * near.promiseBatchActionAddKeyWithFullAccess(
+ *  promise,
+ *  [5, 11, 41, 58, 248, ...],
+ *  572981
+ * );
+ * ```
  */
 export declare function promiseBatchActionAddKeyWithFullAccess(promiseIndex: PromiseIndex, publicKey: Uint8Array, nonce: number | bigint): void;
 /**
@@ -278,6 +620,24 @@ export declare function promiseBatchActionAddKeyWithFullAccess(promiseIndex: Pro
  * @param allowance - The allowance of the access key.
  * @param receiverId - The account ID of the receiver.
  * @param methodNames - The names of the method to allow the key for.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("receiver.near");
+ *
+ * near.promiseBatchActionCreateAccount(promise);
+ *
+ * near.promiseBatchActionAddKeyWithFunctionCall(
+ *  promise,
+ *  [5, 11, 41, 58, 248, ...],
+ *  572981,
+ *  bigint("25000000000000000000000"),
+ *  "counter.near",
+ *  "increase,decrease"
+ * );
+ * ```
  */
 export declare function promiseBatchActionAddKeyWithFunctionCall(promiseIndex: PromiseIndex, publicKey: Uint8Array, nonce: number | bigint, allowance: NearAmount, receiverId: string, methodNames: string): void;
 /**
@@ -285,6 +645,15 @@ export declare function promiseBatchActionAddKeyWithFunctionCall(promiseIndex: P
  *
  * @param promiseIndex - The index of the promise to attach a delete key action to.
  * @param publicKey - The public key to delete.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("receiver.near");
+ *
+ * near.promiseBatchActionDeleteKey(promise, [2, 4, 69, 26, 253, 129, ...]);
+ * ```
  */
 export declare function promiseBatchActionDeleteKey(promiseIndex: PromiseIndex, publicKey: Uint8Array): void;
 /**
@@ -292,6 +661,15 @@ export declare function promiseBatchActionDeleteKey(promiseIndex: PromiseIndex,
  *
  * @param promiseIndex - The index of the promise to attach a delete account action to.
  * @param beneficiaryId - The account ID of the beneficiary - the account that receives the remaining amount of NEAR.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("receiver.near");
+ *
+ * near.promiseBatchActionDeleteAccount(promise, "beneficiary.near");
+ * ```
  */
 export declare function promiseBatchActionDeleteAccount(promiseIndex: PromiseIndex, beneficiaryId: string): void;
 /**
@@ -314,10 +692,33 @@ export declare function promiseBatchActionFunctionCallWeightRaw(promiseIndex: Pr
  * @param amount - The amount of NEAR to attach to the call.
  * @param gas - The amount of Gas to attach to the call.
  * @param weight - The weight of unused Gas to use.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("counter.near");
+ *
+ * near.promiseBatchActionFunctionCallWeight(
+ *  promise,
+ *  "increase",
+ *  `{"value": 5}`,
+ *  bigint("0"),
+ *  bigint("30000000000000"),
+ *  bigint("1")
+ * );
+ * ```
  */
 export declare function promiseBatchActionFunctionCallWeight(promiseIndex: PromiseIndex, methodName: string, args: string, amount: NearAmount, gas: NearAmount, weight: GasWeight): void;
 /**
  * The number of promise results available.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.promiseResultsCount(); // -> bigint("1")
+ * ```
  */
 export declare function promiseResultsCount(): bigint;
 /**
@@ -330,36 +731,86 @@ export declare function promiseResultRaw(promiseIndex: PromiseIndex): Uint8Array
  * Returns the result of the NEAR promise for the passed promise index as utf-8 string
  *
  * @param promiseIndex - The index of the promise to return the result for.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.promiseResult(0); // -> `{"key": "value", "nested": {"key2": "value2"}}`
+ * ```
  */
 export declare function promiseResult(promiseIndex: PromiseIndex): string;
 /**
  * Executes the promise in the NEAR WASM virtual machine.
+ * Consider the execution result of promise under promiseIndex as execution result of this function.
  *
  * @param promiseIndex - The index of the promise to execute.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseCreate(
+ *  "contract.near",
+ *  "increase",
+ *  `{"value": 5}`,
+ *  bigint("0"),
+ *  bigint("30000000000000")
+ * );
+ * near.promiseReturn(promise);
+ * ```
  */
 export declare function promiseReturn(promiseIndex: PromiseIndex): void;
 /**
- * Returns sha256 hash of given value
+ * Returns sha256 hash of given value. This returns a 32 byte hash.
  * @param value - value to be hashed, in Bytes
  * @returns hash result in Bytes
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.sha256([1, 4, 18, 31, 5, 91, 224]); // -> [0, 7, 18, 94, 228, 11, 15, ...]
+ * ```
  */
 export declare function sha256(value: Uint8Array): Uint8Array;
 /**
  * Returns keccak256 hash of given value
  * @param value - value to be hashed, in Bytes
  * @returns hash result in Bytes
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.keccak256([0, 24, 81, 31]); // -> [1, 3, 48, 94, 248, 11, 35, ...]
+ * ```
  */
 export declare function keccak256(value: Uint8Array): Uint8Array;
 /**
  * Returns keccak512 hash of given value
  * @param value - value to be hashed, in Bytes
  * @returns hash result in Bytes
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.keccak512([0, 24, 81, 31]); // -> [1, 3, 48, 94, 248, 11, 35, ...]
+ * ```
  */
 export declare function keccak512(value: Uint8Array): Uint8Array;
 /**
- * Returns ripemd160 hash of given value
+ * Returns ripemd160 hash of given value. This returns a 20 byte hash.
  * @param value - value to be hashed, in Bytes
  * @returns hash result in Bytes
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.ripemd160([5, 14, 51, 31, 15, 69]); // -> [2, 0, 0, 0, 18, 11, 65, ...]
+ * ```
  */
 export declare function ripemd160(value: Uint8Array): Uint8Array;
 /**
@@ -376,6 +827,8 @@ export declare function ripemd160(value: Uint8Array): Uint8Array;
 export declare function ecrecover(hash: Uint8Array, sig: Uint8Array, v: number, malleabilityFlag: number): Uint8Array | null;
 /**
  * Panic the transaction execution with given message
+ * There's no way to panic with a utf-8 string, use "throw Error(msg)" for that
+ *
  * @param msg - panic message in raw bytes, which should be a valid UTF-8 sequence
  */
 export declare function panicUtf8(msg: Uint8Array): never;
@@ -390,14 +843,31 @@ export declare function logUtf8(msg: Uint8Array): void;
  */
 export declare function logUtf16(msg: Uint8Array): void;
 /**
- * Returns the number of staked NEAR of given validator, in yoctoNEAR
+ * Returns the number of staked NEAR of given validator, in yoctoNEAR.
+ * If the account is not a validator, returns 0.
+ *
  * @param accountId - validator's AccountID
  * @returns - staked amount
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.validatorStake("non-validator.near"); // -> bigint("0")
+ * near.validatorStake("validator.near"); // -> bigint("157201939492990")
+ * ```
  */
 export declare function validatorStake(accountId: string): bigint;
 /**
- * Returns the number of staked NEAR of all validators, in yoctoNEAR
+ * Returns the number of staked NEAR of all validators, in yoctoNEAR, in the current epoch.
  * @returns total staked amount
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.validatorTotalStake(); // -> bigint("412929490100000")
+ * ```
  */
 export declare function validatorTotalStake(): bigint;
 /**
@@ -411,6 +881,8 @@ export declare function validatorTotalStake(): bigint;
  * `[((u256, u256), u256)]` slice.
  *
  * @returns multi exp sum
+ *
+ * @see [EIP-196](https://eips.ethereum.org/EIPS/eip-196)
  */
 export declare function altBn128G1Multiexp(value: Uint8Array): Uint8Array;
 /**
@@ -424,6 +896,8 @@ export declare function altBn128G1Multiexp(value: Uint8Array): Uint8Array;
  * `[((u256, u256), ((u256, u256), (u256, u256)))]` slice.
  *
  * @returns sum over Fq.
+ *
+ * @see [EIP-196](https://eips.ethereum.org/EIPS/eip-196)
  */
 export declare function altBn128G1Sum(value: Uint8Array): Uint8Array;
 /**
@@ -440,5 +914,7 @@ export declare function altBn128G1Sum(value: Uint8Array): Uint8Array;
  * `[((u256, u256), ((u256, u256), (u256, u256)))]` slice.
  *
  * @returns whether pairing check pass
+ *
+ * @see [EIP-197](https://eips.ethereum.org/EIPS/eip-197)
  */
 export declare function altBn128PairingCheck(value: Uint8Array): boolean;
diff --git a/packages/near-sdk-js/lib/api.js b/packages/near-sdk-js/lib/api.js
index 49f915dcf..63f4ab7fd 100644
--- a/packages/near-sdk-js/lib/api.js
+++ b/packages/near-sdk-js/lib/api.js
@@ -1,11 +1,26 @@
+/**
+ * Blockchain-specific methods available to the smart contract.
+ * @module near
+ * */
 import { assert, str, encode, decode, } from "./utils";
 import { PromiseResult } from "./types";
 const U64_MAX = 2n ** 64n - 1n;
 const EVICTED_REGISTER = U64_MAX - 1n;
 /**
  * Logs parameters in the NEAR WASM virtual machine.
+ * This message is stored on chain.
  *
  * @param params - Parameters to log.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.log("hello world"); // -> "hello world"
+ * near.log("key", 2024); // -> "key 2024"
+ * near.log("user", { id: 1, name: "Test" }); // `user {"id": 1, "name": "Test"}`
+ * near.log("text", undefined, "user", { id: 1, name: "Test" }); // `text undefined user {"id": 1, "name": "Test"}`
+ * ```
  */
 export function log(...params) {
     env.log(params.reduce((accumulated, parameter, index) => {
@@ -22,6 +37,13 @@ export function log(...params) {
 /**
  * Returns the account ID of the account that signed the transaction.
  * Can only be called in a call or initialize function.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.signerAccountId(); // -> "test.near"
+ * ```
  */
 export function signerAccountId() {
     env.signer_account_id(0);
@@ -30,6 +52,13 @@ export function signerAccountId() {
 /**
  * Returns the public key of the account that signed the transaction.
  * Can only be called in a call or initialize function.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.signerAccountPk(); // -> [56, 91, 91, 85, 17, 172, 223, ...]
+ * ```
  */
 export function signerAccountPk() {
     env.signer_account_pk(0);
@@ -38,6 +67,13 @@ export function signerAccountPk() {
 /**
  * Returns the account ID of the account that called the function.
  * Can only be called in a call or initialize function.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.predecessorAccountId(); // -> "caller.near"
+ * ```
  */
 export function predecessorAccountId() {
     env.predecessor_account_id(0);
@@ -45,6 +81,14 @@ export function predecessorAccountId() {
 }
 /**
  * Returns the account ID of the current contract - the contract that is being executed.
+ * The id of the account that owns the current contract.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.currentAccountId(); // -> "example.near"
+ * ```
  */
 export function currentAccountId() {
     env.current_account_id(0);
@@ -52,24 +96,52 @@ export function currentAccountId() {
 }
 /**
  * Returns the current block index.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.blockIndex(); // -> bigint("681923959192")
+ * ```
  */
 export function blockIndex() {
     return env.block_index();
 }
 /**
  * Returns the current block height.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.blockHeight(); // -> bigint("681923959192")
+ * ```
  */
 export function blockHeight() {
     return blockIndex();
 }
 /**
- * Returns the current block timestamp.
+ * Returns the current block timestamp, number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.blockTimestamp(); // -> bigint("1704124941241242141")
+ * ```
  */
 export function blockTimestamp() {
     return env.block_timestamp();
 }
 /**
  * Returns the current epoch height.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.epochHeight(); // -> bigint("185829414")
+ * ```
  */
 export function epochHeight() {
     return env.epoch_height();
@@ -77,30 +149,65 @@ export function epochHeight() {
 /**
  * Returns the amount of NEAR attached to this function call.
  * Can only be called in payable functions.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.attachedDeposit(); // -> bigint("210000000000000")
+ * ```
  */
 export function attachedDeposit() {
     return env.attached_deposit();
 }
 /**
  * Returns the amount of Gas that was attached to this function call.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.prepaidGas(); // -> bigint("30000000000000")
+ * ```
  */
 export function prepaidGas() {
     return env.prepaid_gas();
 }
 /**
  * Returns the amount of Gas that has been used by this function call until now.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.usedGas(); // -> bigint("5003005000000")
+ * ```
  */
 export function usedGas() {
     return env.used_gas();
 }
 /**
- * Returns the current account's account balance.
+ * Returns the current account's account balance. This includes the attached_deposit that was attached to the transaction.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.accountBalance(); // -> bigint("10500000210000000")
+ * ```
  */
 export function accountBalance() {
     return env.account_balance();
 }
 /**
- * Returns the current account's locked balance.
+ * Returns the current account's locked balance. The balance locked for potential validator staking.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.accountLockedBalance(); // -> bigint("10500000210000000")
+ * ```
  */
 export function accountLockedBalance() {
     return env.account_locked_balance();
@@ -121,6 +228,15 @@ export function storageReadRaw(key) {
  * Reads the utf-8 string value from NEAR storage that is stored under the provided key.
  *
  * @param key - The utf-8 string key to read from storage.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.storageRead("key"); // -> null
+ * near.storageWrite("key", "value");
+ * near.storageRead("key"); // -> "value"
+ * ```
  */
 export function storageRead(key) {
     const ret = storageReadRaw(encode(key));
@@ -141,6 +257,15 @@ export function storageHasKeyRaw(key) {
  * Checks for the existence of a value under the provided utf-8 string key in NEAR storage.
  *
  * @param key - The utf-8 string key to check for in storage.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.storageHasKey("key"); // -> false
+ * near.storageWrite("key", "value");
+ * near.storageHasKey("key"); // -> true
+ * ```
  */
 export function storageHasKey(key) {
     return storageHasKeyRaw(encode(key));
@@ -153,12 +278,33 @@ export function storageGetEvictedRaw() {
 }
 /**
  * Get the last written or removed value from NEAR storage as utf-8 string.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.storageWrite("key", "value111");
+ * near.storageGetEvicted(); // -> "value111"
+ *
+ * near.storageWrite("key2", "value222");
+ * near.storageGetEvicted(); // -> "value222"
+ *
+ * near.storageRemove("key");
+ * near.storageGetEvicted(); // -> "value111"
+ * ```
  */
 export function storageGetEvicted() {
     return decode(storageGetEvictedRaw());
 }
 /**
  * Returns the current accounts NEAR storage usage.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.storageUsage(); // -> bigint("73841284183493")
+ * ```
  */
 export function storageUsage() {
     return env.storage_usage();
@@ -177,6 +323,15 @@ export function storageWriteRaw(key, value) {
  *
  * @param key - The utf-8 string key under which to store the value.
  * @param value - The utf-8 string value to store.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.storageRead("key"); // -> null
+ * near.storageWrite("key", "value");
+ * near.storageRead("key"); // -> "value"
+ * ```
  */
 export function storageWrite(key, value) {
     return storageWriteRaw(encode(key), encode(value));
@@ -193,18 +348,43 @@ export function storageRemoveRaw(key) {
  * Removes the value of the provided utf-8 string key from NEAR storage.
  *
  * @param key - The utf-8 string key to be removed.
+ *
+ * @returns Removes the value stored under the given key. If key-value existed returns true, otherwise false.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.storageRemove("key"); // -> false
+ * near.storageWrite("key", "value");
+ * near.storageRemove("key"); // -> true
+ * ```
  */
 export function storageRemove(key) {
     return storageRemoveRaw(encode(key));
 }
 /**
  * Returns the cost of storing 0 Byte on NEAR storage.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.storageByteCost(); // -> bigint("10000000000000000000")
+ * ```
  */
 export function storageByteCost() {
     return 10000000000000000000n;
 }
 /**
- * Returns the arguments passed to the current smart contract call.
+ * Returns the arguments passed to the current smart contract call as bytes.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.inputRaw(); // -> Uint8Array([0, 128, 255, 15, ...])
+ * ```
  */
 export function inputRaw() {
     env.input(0);
@@ -212,6 +392,13 @@ export function inputRaw() {
 }
 /**
  * Returns the arguments passed to the current smart contract call as utf-8 string.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.input(); // -> `{"key": "value"}`
+ * ```
  */
 export function input() {
     return decode(inputRaw());
@@ -226,14 +413,34 @@ export function valueReturnRaw(value) {
 }
 /**
  * Returns the utf-8 string value from the NEAR WASM virtual machine.
+ * Sets the utf-8 string as the return value of this function.
  *
  * @param value - The utf-8 string value to return.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const user = {
+ *  id: 128,
+ *  name: "Test",
+ *  key: "value"
+ * };
+ * near.valueReturn(JSON.stringify(user));
+ * ```
  */
 export function valueReturn(value) {
     valueReturnRaw(encode(value));
 }
 /**
- * Returns a random string of bytes.
+ * Returns a random string of bytes. This returns a 32 byte hash.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.randomSeed(); // -> [2, 4, 98, 124, 0, 224, ...]
+ * ```
  */
 export function randomSeed() {
     env.random_seed(0);
@@ -259,6 +466,19 @@ export function promiseCreateRaw(accountId, methodName, args, amount, gas) {
  * @param args - The utf-8 string arguments to call the method with.
  * @param amount - The amount of NEAR attached to the call.
  * @param gas - The amount of Gas attached to the call.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseCreate(
+ *  "contract.near",
+ *  "increase",
+ *  `{"value": 5}`,
+ *  bigint("0"),
+ *  bigint("30000000000000")
+ * );
+ * ```
  */
 export function promiseCreate(accountId, methodName, args, amount, gas) {
     return promiseCreateRaw(accountId, methodName, encode(args), amount, gas);
@@ -285,6 +505,28 @@ export function promiseThenRaw(promiseIndex, accountId, methodName, args, amount
  * @param args - The utf-8 string arguments to call the method with.
  * @param amount - The amount of NEAR to attach to the call.
  * @param gas - The amount of Gas to attach to the call.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseCreate(
+ *  "contract.near",
+ *  "increase",
+ *  `{"value": 5}`,
+ *  bigint("0"),
+ *  bigint("30000000000000")
+ * );
+ *
+ * const chainedPromise = near.promiseThen(
+ *  promise,
+ *  "contract2.near",
+ *  "set_greeting",
+ *  `{"text": "Hello, world!"}`,
+ *  bigint("1000000000000"),
+ *  bigint("30000000000000")
+ * );
+ * ```
  */
 export function promiseThen(promiseIndex, accountId, methodName, args, amount, gas) {
     return promiseThenRaw(promiseIndex, accountId, methodName, encode(args), amount, gas);
@@ -293,6 +535,19 @@ export function promiseThen(promiseIndex, accountId, methodName, args, amount, g
  * Join an arbitrary array of NEAR promises.
  *
  * @param promiseIndexes - An arbitrary array of NEAR promise indexes to join.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise1 = near.promiseBatchCreate("receiver1.near");
+ * near.promiseBatchActionTransfer(promise1, bigint("10000000000000000"));
+ *
+ * const promise2 = near.promiseBatchCreate("receiver2.near");
+ * near.promiseBatchActionTransfer(promise2, bigint("30500050000000000"));
+ *
+ * const promise = near.promiseAnd(promise1, promise2);
+ * ```
  */
 export function promiseAnd(...promiseIndexes) {
     return env.promise_and(...promiseIndexes);
@@ -301,6 +556,13 @@ export function promiseAnd(...promiseIndexes) {
  * Create a NEAR promise which will have multiple promise actions inside.
  *
  * @param accountId - The account ID of the target contract.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("receiver.near");
+ * ```
  */
 export function promiseBatchCreate(accountId) {
     return env.promise_batch_create(accountId);
@@ -310,6 +572,17 @@ export function promiseBatchCreate(accountId) {
  *
  * @param promiseIndex - The NEAR promise index of the batch.
  * @param accountId - The account ID of the target contract.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise1 = near.promiseBatchCreate("receiver1.near");
+ * near.promiseBatchActionTransfer(promise1, bigint("10000000000000000"));
+ *
+ * const promise2 = near.promiseBatchThen(promise1, "receiver2.near");
+ * near.promiseBatchActionTransfer(promise2, bigint("2500000000000000000"));
+ * ```
  */
 export function promiseBatchThen(promiseIndex, accountId) {
     return env.promise_batch_then(promiseIndex, accountId);
@@ -318,6 +591,15 @@ export function promiseBatchThen(promiseIndex, accountId) {
  * Attach a create account promise action to the NEAR promise index with the provided promise index.
  *
  * @param promiseIndex - The index of the promise to attach a create account action to.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("receiver.near");
+ *
+ * near.promiseBatchActionCreateAccount(promise);
+ * ```
  */
 export function promiseBatchActionCreateAccount(promiseIndex) {
     env.promise_batch_action_create_account(promiseIndex);
@@ -327,6 +609,15 @@ export function promiseBatchActionCreateAccount(promiseIndex) {
  *
  * @param promiseIndex - The index of the promise to attach a deploy contract action to.
  * @param code - The WASM byte code of the contract to be deployed.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("contract.near");
+ *
+ * near.promiseBatchActionDeployContract(promise, [21, 24, 9, 6, 53, 229, ...]);
+ * ```
  */
 export function promiseBatchActionDeployContract(promiseIndex, code) {
     env.promise_batch_action_deploy_contract(promiseIndex, code);
@@ -351,6 +642,21 @@ export function promiseBatchActionFunctionCallRaw(promiseIndex, methodName, args
  * @param args - The utf-8 string arguments to call the method with.
  * @param amount - The amount of NEAR to attach to the call.
  * @param gas - The amount of Gas to attach to the call.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("counter.near");
+ *
+ * near.promiseBatchActionFunctionCall(
+ *  promise,
+ *  "increase",
+ *  `{"value": 5}`,
+ *  bigint("0"),
+ *  bigint("30000000000000")
+ * );
+ * ```
  */
 export function promiseBatchActionFunctionCall(promiseIndex, methodName, args, amount, gas) {
     promiseBatchActionFunctionCallRaw(promiseIndex, methodName, encode(args), amount, gas);
@@ -360,6 +666,14 @@ export function promiseBatchActionFunctionCall(promiseIndex, methodName, args, a
  *
  * @param promiseIndex - The index of the promise to attach a transfer action to.
  * @param amount - The amount of NEAR to transfer.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("receiver.near");
+ * near.promiseBatchActionTransfer(promise, bigint("10000000000000000"));
+ * ```
  */
 export function promiseBatchActionTransfer(promiseIndex, amount) {
     env.promise_batch_action_transfer(promiseIndex, amount);
@@ -370,6 +684,19 @@ export function promiseBatchActionTransfer(promiseIndex, amount) {
  * @param promiseIndex - The index of the promise to attach a stake action to.
  * @param amount - The amount of NEAR to stake.
  * @param publicKey - The public key with which to stake.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("contract.near");
+ *
+ * near.promiseBatchActionStake(
+ *  promise,
+ *  bigint("59319390502334010"),
+ *  [2, 4, 59, 12, 48, 91, ...]
+ * );
+ * ```
  */
 export function promiseBatchActionStake(promiseIndex, amount, publicKey) {
     env.promise_batch_action_stake(promiseIndex, amount, publicKey);
@@ -380,6 +707,21 @@ export function promiseBatchActionStake(promiseIndex, amount, publicKey) {
  * @param promiseIndex - The index of the promise to attach a add full access key action to.
  * @param publicKey - The public key to add as a full access key.
  * @param nonce - The nonce to use.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("receiver.near");
+ *
+ * near.promiseBatchActionCreateAccount(promise);
+ *
+ * near.promiseBatchActionAddKeyWithFullAccess(
+ *  promise,
+ *  [5, 11, 41, 58, 248, ...],
+ *  572981
+ * );
+ * ```
  */
 export function promiseBatchActionAddKeyWithFullAccess(promiseIndex, publicKey, nonce) {
     env.promise_batch_action_add_key_with_full_access(promiseIndex, publicKey, nonce);
@@ -393,6 +735,24 @@ export function promiseBatchActionAddKeyWithFullAccess(promiseIndex, publicKey,
  * @param allowance - The allowance of the access key.
  * @param receiverId - The account ID of the receiver.
  * @param methodNames - The names of the method to allow the key for.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("receiver.near");
+ *
+ * near.promiseBatchActionCreateAccount(promise);
+ *
+ * near.promiseBatchActionAddKeyWithFunctionCall(
+ *  promise,
+ *  [5, 11, 41, 58, 248, ...],
+ *  572981,
+ *  bigint("25000000000000000000000"),
+ *  "counter.near",
+ *  "increase,decrease"
+ * );
+ * ```
  */
 export function promiseBatchActionAddKeyWithFunctionCall(promiseIndex, publicKey, nonce, allowance, receiverId, methodNames) {
     env.promise_batch_action_add_key_with_function_call(promiseIndex, publicKey, nonce, allowance, receiverId, methodNames);
@@ -402,6 +762,15 @@ export function promiseBatchActionAddKeyWithFunctionCall(promiseIndex, publicKey
  *
  * @param promiseIndex - The index of the promise to attach a delete key action to.
  * @param publicKey - The public key to delete.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("receiver.near");
+ *
+ * near.promiseBatchActionDeleteKey(promise, [2, 4, 69, 26, 253, 129, ...]);
+ * ```
  */
 export function promiseBatchActionDeleteKey(promiseIndex, publicKey) {
     env.promise_batch_action_delete_key(promiseIndex, publicKey);
@@ -411,6 +780,15 @@ export function promiseBatchActionDeleteKey(promiseIndex, publicKey) {
  *
  * @param promiseIndex - The index of the promise to attach a delete account action to.
  * @param beneficiaryId - The account ID of the beneficiary - the account that receives the remaining amount of NEAR.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("receiver.near");
+ *
+ * near.promiseBatchActionDeleteAccount(promise, "beneficiary.near");
+ * ```
  */
 export function promiseBatchActionDeleteAccount(promiseIndex, beneficiaryId) {
     env.promise_batch_action_delete_account(promiseIndex, beneficiaryId);
@@ -437,12 +815,35 @@ export function promiseBatchActionFunctionCallWeightRaw(promiseIndex, methodName
  * @param amount - The amount of NEAR to attach to the call.
  * @param gas - The amount of Gas to attach to the call.
  * @param weight - The weight of unused Gas to use.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("counter.near");
+ *
+ * near.promiseBatchActionFunctionCallWeight(
+ *  promise,
+ *  "increase",
+ *  `{"value": 5}`,
+ *  bigint("0"),
+ *  bigint("30000000000000"),
+ *  bigint("1")
+ * );
+ * ```
  */
 export function promiseBatchActionFunctionCallWeight(promiseIndex, methodName, args, amount, gas, weight) {
     promiseBatchActionFunctionCallWeightRaw(promiseIndex, methodName, encode(args), amount, gas, weight);
 }
 /**
  * The number of promise results available.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.promiseResultsCount(); // -> bigint("1")
+ * ```
  */
 export function promiseResultsCount() {
     return env.promise_results_count();
@@ -465,22 +866,51 @@ export function promiseResultRaw(promiseIndex) {
  * Returns the result of the NEAR promise for the passed promise index as utf-8 string
  *
  * @param promiseIndex - The index of the promise to return the result for.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.promiseResult(0); // -> `{"key": "value", "nested": {"key2": "value2"}}`
+ * ```
  */
 export function promiseResult(promiseIndex) {
     return decode(promiseResultRaw(promiseIndex));
 }
 /**
  * Executes the promise in the NEAR WASM virtual machine.
+ * Consider the execution result of promise under promiseIndex as execution result of this function.
  *
  * @param promiseIndex - The index of the promise to execute.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseCreate(
+ *  "contract.near",
+ *  "increase",
+ *  `{"value": 5}`,
+ *  bigint("0"),
+ *  bigint("30000000000000")
+ * );
+ * near.promiseReturn(promise);
+ * ```
  */
 export function promiseReturn(promiseIndex) {
     env.promise_return(promiseIndex);
 }
 /**
- * Returns sha256 hash of given value
+ * Returns sha256 hash of given value. This returns a 32 byte hash.
  * @param value - value to be hashed, in Bytes
  * @returns hash result in Bytes
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.sha256([1, 4, 18, 31, 5, 91, 224]); // -> [0, 7, 18, 94, 228, 11, 15, ...]
+ * ```
  */
 export function sha256(value) {
     env.sha256(value, 0);
@@ -490,6 +920,13 @@ export function sha256(value) {
  * Returns keccak256 hash of given value
  * @param value - value to be hashed, in Bytes
  * @returns hash result in Bytes
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.keccak256([0, 24, 81, 31]); // -> [1, 3, 48, 94, 248, 11, 35, ...]
+ * ```
  */
 export function keccak256(value) {
     env.keccak256(value, 0);
@@ -499,15 +936,29 @@ export function keccak256(value) {
  * Returns keccak512 hash of given value
  * @param value - value to be hashed, in Bytes
  * @returns hash result in Bytes
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.keccak512([0, 24, 81, 31]); // -> [1, 3, 48, 94, 248, 11, 35, ...]
+ * ```
  */
 export function keccak512(value) {
     env.keccak512(value, 0);
     return env.read_register(0);
 }
 /**
- * Returns ripemd160 hash of given value
+ * Returns ripemd160 hash of given value. This returns a 20 byte hash.
  * @param value - value to be hashed, in Bytes
  * @returns hash result in Bytes
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.ripemd160([5, 14, 51, 31, 15, 69]); // -> [2, 0, 0, 0, 18, 11, 65, ...]
+ * ```
  */
 export function ripemd160(value) {
     env.ripemd160(value, 0);
@@ -534,6 +985,8 @@ export function ecrecover(hash, sig, v, malleabilityFlag) {
 // NOTE: "env.panic(msg)" is not exported, use "throw Error(msg)" instead
 /**
  * Panic the transaction execution with given message
+ * There's no way to panic with a utf-8 string, use "throw Error(msg)" for that
+ *
  * @param msg - panic message in raw bytes, which should be a valid UTF-8 sequence
  */
 export function panicUtf8(msg) {
@@ -554,16 +1007,33 @@ export function logUtf16(msg) {
     env.log_utf16(msg);
 }
 /**
- * Returns the number of staked NEAR of given validator, in yoctoNEAR
+ * Returns the number of staked NEAR of given validator, in yoctoNEAR.
+ * If the account is not a validator, returns 0.
+ *
  * @param accountId - validator's AccountID
  * @returns - staked amount
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.validatorStake("non-validator.near"); // -> bigint("0")
+ * near.validatorStake("validator.near"); // -> bigint("157201939492990")
+ * ```
  */
 export function validatorStake(accountId) {
     return env.validator_stake(accountId);
 }
 /**
- * Returns the number of staked NEAR of all validators, in yoctoNEAR
+ * Returns the number of staked NEAR of all validators, in yoctoNEAR, in the current epoch.
  * @returns total staked amount
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.validatorTotalStake(); // -> bigint("412929490100000")
+ * ```
  */
 export function validatorTotalStake() {
     return env.validator_total_stake();
@@ -579,6 +1049,8 @@ export function validatorTotalStake() {
  * `[((u256, u256), u256)]` slice.
  *
  * @returns multi exp sum
+ *
+ * @see [EIP-196](https://eips.ethereum.org/EIPS/eip-196)
  */
 export function altBn128G1Multiexp(value) {
     env.alt_bn128_g1_multiexp(value, 0);
@@ -595,6 +1067,8 @@ export function altBn128G1Multiexp(value) {
  * `[((u256, u256), ((u256, u256), (u256, u256)))]` slice.
  *
  * @returns sum over Fq.
+ *
+ * @see [EIP-196](https://eips.ethereum.org/EIPS/eip-196)
  */
 export function altBn128G1Sum(value) {
     env.alt_bn128_g1_sum(value, 0);
@@ -614,6 +1088,8 @@ export function altBn128G1Sum(value) {
  * `[((u256, u256), ((u256, u256), (u256, u256)))]` slice.
  *
  * @returns whether pairing check pass
+ *
+ * @see [EIP-197](https://eips.ethereum.org/EIPS/eip-197)
  */
 export function altBn128PairingCheck(value) {
     return env.alt_bn128_pairing_check(value) === 1n;
diff --git a/packages/near-sdk-js/src/api.ts b/packages/near-sdk-js/src/api.ts
index 172b05914..18805da1e 100644
--- a/packages/near-sdk-js/src/api.ts
+++ b/packages/near-sdk-js/src/api.ts
@@ -1,3 +1,7 @@
+/**
+ * Blockchain-specific methods available to the smart contract.
+ * @module near
+ * */
 import {
   assert,
   NearAmount,
@@ -154,8 +158,19 @@ declare const env: Env;
 
 /**
  * Logs parameters in the NEAR WASM virtual machine.
+ * This message is stored on chain.
  *
  * @param params - Parameters to log.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.log("hello world"); // -> "hello world"
+ * near.log("key", 2024); // -> "key 2024"
+ * near.log("user", { id: 1, name: "Test" }); // `user {"id": 1, "name": "Test"}`
+ * near.log("text", undefined, "user", { id: 1, name: "Test" }); // `text undefined user {"id": 1, "name": "Test"}`
+ * ```
  */
 export function log(...params: unknown[]): void {
   env.log(
@@ -178,6 +193,13 @@ export function log(...params: unknown[]): void {
 /**
  * Returns the account ID of the account that signed the transaction.
  * Can only be called in a call or initialize function.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.signerAccountId(); // -> "test.near"
+ * ```
  */
 export function signerAccountId(): string {
   env.signer_account_id(0);
@@ -187,6 +209,13 @@ export function signerAccountId(): string {
 /**
  * Returns the public key of the account that signed the transaction.
  * Can only be called in a call or initialize function.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.signerAccountPk(); // -> [56, 91, 91, 85, 17, 172, 223, ...]
+ * ```
  */
 export function signerAccountPk(): Uint8Array {
   env.signer_account_pk(0);
@@ -196,6 +225,13 @@ export function signerAccountPk(): Uint8Array {
 /**
  * Returns the account ID of the account that called the function.
  * Can only be called in a call or initialize function.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.predecessorAccountId(); // -> "caller.near"
+ * ```
  */
 export function predecessorAccountId(): string {
   env.predecessor_account_id(0);
@@ -204,6 +240,14 @@ export function predecessorAccountId(): string {
 
 /**
  * Returns the account ID of the current contract - the contract that is being executed.
+ * The id of the account that owns the current contract.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.currentAccountId(); // -> "example.near"
+ * ```
  */
 export function currentAccountId(): string {
   env.current_account_id(0);
@@ -212,6 +256,13 @@ export function currentAccountId(): string {
 
 /**
  * Returns the current block index.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.blockIndex(); // -> bigint("681923959192")
+ * ```
  */
 export function blockIndex(): bigint {
   return env.block_index();
@@ -219,13 +270,27 @@ export function blockIndex(): bigint {
 
 /**
  * Returns the current block height.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.blockHeight(); // -> bigint("681923959192")
+ * ```
  */
 export function blockHeight(): bigint {
   return blockIndex();
 }
 
 /**
- * Returns the current block timestamp.
+ * Returns the current block timestamp, number of non-leap-nanoseconds since January 1, 1970 0:00:00 UTC.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.blockTimestamp(); // -> bigint("1704124941241242141")
+ * ```
  */
 export function blockTimestamp(): bigint {
   return env.block_timestamp();
@@ -233,6 +298,13 @@ export function blockTimestamp(): bigint {
 
 /**
  * Returns the current epoch height.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.epochHeight(); // -> bigint("185829414")
+ * ```
  */
 export function epochHeight(): bigint {
   return env.epoch_height();
@@ -241,6 +313,13 @@ export function epochHeight(): bigint {
 /**
  * Returns the amount of NEAR attached to this function call.
  * Can only be called in payable functions.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.attachedDeposit(); // -> bigint("210000000000000")
+ * ```
  */
 export function attachedDeposit(): bigint {
   return env.attached_deposit();
@@ -248,6 +327,13 @@ export function attachedDeposit(): bigint {
 
 /**
  * Returns the amount of Gas that was attached to this function call.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.prepaidGas(); // -> bigint("30000000000000")
+ * ```
  */
 export function prepaidGas(): bigint {
   return env.prepaid_gas();
@@ -255,20 +341,41 @@ export function prepaidGas(): bigint {
 
 /**
  * Returns the amount of Gas that has been used by this function call until now.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.usedGas(); // -> bigint("5003005000000")
+ * ```
  */
 export function usedGas(): bigint {
   return env.used_gas();
 }
 
 /**
- * Returns the current account's account balance.
+ * Returns the current account's account balance. This includes the attached_deposit that was attached to the transaction.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.accountBalance(); // -> bigint("10500000210000000")
+ * ```
  */
 export function accountBalance(): bigint {
   return env.account_balance();
 }
 
 /**
- * Returns the current account's locked balance.
+ * Returns the current account's locked balance. The balance locked for potential validator staking.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.accountLockedBalance(); // -> bigint("10500000210000000")
+ * ```
  */
 export function accountLockedBalance(): bigint {
   return env.account_locked_balance();
@@ -293,6 +400,15 @@ export function storageReadRaw(key: Uint8Array): Uint8Array | null {
  * Reads the utf-8 string value from NEAR storage that is stored under the provided key.
  *
  * @param key - The utf-8 string key to read from storage.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.storageRead("key"); // -> null
+ * near.storageWrite("key", "value");
+ * near.storageRead("key"); // -> "value"
+ * ```
  */
 export function storageRead(key: string): string | null {
   const ret = storageReadRaw(encode(key));
@@ -315,6 +431,15 @@ export function storageHasKeyRaw(key: Uint8Array): boolean {
  * Checks for the existence of a value under the provided utf-8 string key in NEAR storage.
  *
  * @param key - The utf-8 string key to check for in storage.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.storageHasKey("key"); // -> false
+ * near.storageWrite("key", "value");
+ * near.storageHasKey("key"); // -> true
+ * ```
  */
 export function storageHasKey(key: string): boolean {
   return storageHasKeyRaw(encode(key));
@@ -329,6 +454,20 @@ export function storageGetEvictedRaw(): Uint8Array {
 
 /**
  * Get the last written or removed value from NEAR storage as utf-8 string.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.storageWrite("key", "value111");
+ * near.storageGetEvicted(); // -> "value111"
+ *
+ * near.storageWrite("key2", "value222");
+ * near.storageGetEvicted(); // -> "value222"
+ *
+ * near.storageRemove("key");
+ * near.storageGetEvicted(); // -> "value111"
+ * ```
  */
 export function storageGetEvicted(): string {
   return decode(storageGetEvictedRaw());
@@ -336,6 +475,13 @@ export function storageGetEvicted(): string {
 
 /**
  * Returns the current accounts NEAR storage usage.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.storageUsage(); // -> bigint("73841284183493")
+ * ```
  */
 export function storageUsage(): bigint {
   return env.storage_usage();
@@ -356,6 +502,15 @@ export function storageWriteRaw(key: Uint8Array, value: Uint8Array): boolean {
  *
  * @param key - The utf-8 string key under which to store the value.
  * @param value - The utf-8 string value to store.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.storageRead("key"); // -> null
+ * near.storageWrite("key", "value");
+ * near.storageRead("key"); // -> "value"
+ * ```
  */
 export function storageWrite(key: string, value: string): boolean {
   return storageWriteRaw(encode(key), encode(value));
@@ -374,6 +529,17 @@ export function storageRemoveRaw(key: Uint8Array): boolean {
  * Removes the value of the provided utf-8 string key from NEAR storage.
  *
  * @param key - The utf-8 string key to be removed.
+ *
+ * @returns Removes the value stored under the given key. If key-value existed returns true, otherwise false.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.storageRemove("key"); // -> false
+ * near.storageWrite("key", "value");
+ * near.storageRemove("key"); // -> true
+ * ```
  */
 export function storageRemove(key: string): boolean {
   return storageRemoveRaw(encode(key));
@@ -381,13 +547,27 @@ export function storageRemove(key: string): boolean {
 
 /**
  * Returns the cost of storing 0 Byte on NEAR storage.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.storageByteCost(); // -> bigint("10000000000000000000")
+ * ```
  */
 export function storageByteCost(): bigint {
   return 10_000_000_000_000_000_000n;
 }
 
 /**
- * Returns the arguments passed to the current smart contract call.
+ * Returns the arguments passed to the current smart contract call as bytes.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.inputRaw(); // -> Uint8Array([0, 128, 255, 15, ...])
+ * ```
  */
 export function inputRaw(): Uint8Array {
   env.input(0);
@@ -396,6 +576,13 @@ export function inputRaw(): Uint8Array {
 
 /**
  * Returns the arguments passed to the current smart contract call as utf-8 string.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.input(); // -> `{"key": "value"}`
+ * ```
  */
 export function input(): string {
   return decode(inputRaw());
@@ -412,15 +599,35 @@ export function valueReturnRaw(value: Uint8Array): void {
 
 /**
  * Returns the utf-8 string value from the NEAR WASM virtual machine.
+ * Sets the utf-8 string as the return value of this function.
  *
  * @param value - The utf-8 string value to return.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const user = {
+ *  id: 128,
+ *  name: "Test",
+ *  key: "value"
+ * };
+ * near.valueReturn(JSON.stringify(user));
+ * ```
  */
 export function valueReturn(value: string): void {
   valueReturnRaw(encode(value));
 }
 
 /**
- * Returns a random string of bytes.
+ * Returns a random string of bytes. This returns a 32 byte hash.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.randomSeed(); // -> [2, 4, 98, 124, 0, 224, ...]
+ * ```
  */
 export function randomSeed(): Uint8Array {
   env.random_seed(0);
@@ -460,6 +667,19 @@ export function promiseCreateRaw(
  * @param args - The utf-8 string arguments to call the method with.
  * @param amount - The amount of NEAR attached to the call.
  * @param gas - The amount of Gas attached to the call.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseCreate(
+ *  "contract.near",
+ *  "increase",
+ *  `{"value": 5}`,
+ *  bigint("0"),
+ *  bigint("30000000000000")
+ * );
+ * ```
  */
 export function promiseCreate(
   accountId: string,
@@ -508,6 +728,28 @@ export function promiseThenRaw(
  * @param args - The utf-8 string arguments to call the method with.
  * @param amount - The amount of NEAR to attach to the call.
  * @param gas - The amount of Gas to attach to the call.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseCreate(
+ *  "contract.near",
+ *  "increase",
+ *  `{"value": 5}`,
+ *  bigint("0"),
+ *  bigint("30000000000000")
+ * );
+ *
+ * const chainedPromise = near.promiseThen(
+ *  promise,
+ *  "contract2.near",
+ *  "set_greeting",
+ *  `{"text": "Hello, world!"}`,
+ *  bigint("1000000000000"),
+ *  bigint("30000000000000")
+ * );
+ * ```
  */
 export function promiseThen(
   promiseIndex: PromiseIndex,
@@ -531,6 +773,19 @@ export function promiseThen(
  * Join an arbitrary array of NEAR promises.
  *
  * @param promiseIndexes - An arbitrary array of NEAR promise indexes to join.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise1 = near.promiseBatchCreate("receiver1.near");
+ * near.promiseBatchActionTransfer(promise1, bigint("10000000000000000"));
+ *
+ * const promise2 = near.promiseBatchCreate("receiver2.near");
+ * near.promiseBatchActionTransfer(promise2, bigint("30500050000000000"));
+ *
+ * const promise = near.promiseAnd(promise1, promise2);
+ * ```
  */
 export function promiseAnd(...promiseIndexes: PromiseIndex[]): PromiseIndex {
   return env.promise_and(
@@ -542,6 +797,13 @@ export function promiseAnd(...promiseIndexes: PromiseIndex[]): PromiseIndex {
  * Create a NEAR promise which will have multiple promise actions inside.
  *
  * @param accountId - The account ID of the target contract.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("receiver.near");
+ * ```
  */
 export function promiseBatchCreate(accountId: string): PromiseIndex {
   return env.promise_batch_create(accountId) as unknown as PromiseIndex;
@@ -552,6 +814,17 @@ export function promiseBatchCreate(accountId: string): PromiseIndex {
  *
  * @param promiseIndex - The NEAR promise index of the batch.
  * @param accountId - The account ID of the target contract.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise1 = near.promiseBatchCreate("receiver1.near");
+ * near.promiseBatchActionTransfer(promise1, bigint("10000000000000000"));
+ *
+ * const promise2 = near.promiseBatchThen(promise1, "receiver2.near");
+ * near.promiseBatchActionTransfer(promise2, bigint("2500000000000000000"));
+ * ```
  */
 export function promiseBatchThen(
   promiseIndex: PromiseIndex,
@@ -567,6 +840,15 @@ export function promiseBatchThen(
  * Attach a create account promise action to the NEAR promise index with the provided promise index.
  *
  * @param promiseIndex - The index of the promise to attach a create account action to.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("receiver.near");
+ *
+ * near.promiseBatchActionCreateAccount(promise);
+ * ```
  */
 export function promiseBatchActionCreateAccount(
   promiseIndex: PromiseIndex
@@ -579,6 +861,15 @@ export function promiseBatchActionCreateAccount(
  *
  * @param promiseIndex - The index of the promise to attach a deploy contract action to.
  * @param code - The WASM byte code of the contract to be deployed.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("contract.near");
+ *
+ * near.promiseBatchActionDeployContract(promise, [21, 24, 9, 6, 53, 229, ...]);
+ * ```
  */
 export function promiseBatchActionDeployContract(
   promiseIndex: PromiseIndex,
@@ -623,6 +914,21 @@ export function promiseBatchActionFunctionCallRaw(
  * @param args - The utf-8 string arguments to call the method with.
  * @param amount - The amount of NEAR to attach to the call.
  * @param gas - The amount of Gas to attach to the call.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("counter.near");
+ *
+ * near.promiseBatchActionFunctionCall(
+ *  promise,
+ *  "increase",
+ *  `{"value": 5}`,
+ *  bigint("0"),
+ *  bigint("30000000000000")
+ * );
+ * ```
  */
 export function promiseBatchActionFunctionCall(
   promiseIndex: PromiseIndex,
@@ -645,6 +951,14 @@ export function promiseBatchActionFunctionCall(
  *
  * @param promiseIndex - The index of the promise to attach a transfer action to.
  * @param amount - The amount of NEAR to transfer.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("receiver.near");
+ * near.promiseBatchActionTransfer(promise, bigint("10000000000000000"));
+ * ```
  */
 export function promiseBatchActionTransfer(
   promiseIndex: PromiseIndex,
@@ -659,6 +973,19 @@ export function promiseBatchActionTransfer(
  * @param promiseIndex - The index of the promise to attach a stake action to.
  * @param amount - The amount of NEAR to stake.
  * @param publicKey - The public key with which to stake.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("contract.near");
+ *
+ * near.promiseBatchActionStake(
+ *  promise,
+ *  bigint("59319390502334010"),
+ *  [2, 4, 59, 12, 48, 91, ...]
+ * );
+ * ```
  */
 export function promiseBatchActionStake(
   promiseIndex: PromiseIndex,
@@ -678,6 +1005,21 @@ export function promiseBatchActionStake(
  * @param promiseIndex - The index of the promise to attach a add full access key action to.
  * @param publicKey - The public key to add as a full access key.
  * @param nonce - The nonce to use.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("receiver.near");
+ *
+ * near.promiseBatchActionCreateAccount(promise);
+ *
+ * near.promiseBatchActionAddKeyWithFullAccess(
+ *  promise,
+ *  [5, 11, 41, 58, 248, ...],
+ *  572981
+ * );
+ * ```
  */
 export function promiseBatchActionAddKeyWithFullAccess(
   promiseIndex: PromiseIndex,
@@ -700,6 +1042,24 @@ export function promiseBatchActionAddKeyWithFullAccess(
  * @param allowance - The allowance of the access key.
  * @param receiverId - The account ID of the receiver.
  * @param methodNames - The names of the method to allow the key for.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("receiver.near");
+ *
+ * near.promiseBatchActionCreateAccount(promise);
+ *
+ * near.promiseBatchActionAddKeyWithFunctionCall(
+ *  promise,
+ *  [5, 11, 41, 58, 248, ...],
+ *  572981,
+ *  bigint("25000000000000000000000"),
+ *  "counter.near",
+ *  "increase,decrease"
+ * );
+ * ```
  */
 export function promiseBatchActionAddKeyWithFunctionCall(
   promiseIndex: PromiseIndex,
@@ -724,6 +1084,15 @@ export function promiseBatchActionAddKeyWithFunctionCall(
  *
  * @param promiseIndex - The index of the promise to attach a delete key action to.
  * @param publicKey - The public key to delete.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("receiver.near");
+ *
+ * near.promiseBatchActionDeleteKey(promise, [2, 4, 69, 26, 253, 129, ...]);
+ * ```
  */
 export function promiseBatchActionDeleteKey(
   promiseIndex: PromiseIndex,
@@ -740,6 +1109,15 @@ export function promiseBatchActionDeleteKey(
  *
  * @param promiseIndex - The index of the promise to attach a delete account action to.
  * @param beneficiaryId - The account ID of the beneficiary - the account that receives the remaining amount of NEAR.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("receiver.near");
+ *
+ * near.promiseBatchActionDeleteAccount(promise, "beneficiary.near");
+ * ```
  */
 export function promiseBatchActionDeleteAccount(
   promiseIndex: PromiseIndex,
@@ -788,6 +1166,22 @@ export function promiseBatchActionFunctionCallWeightRaw(
  * @param amount - The amount of NEAR to attach to the call.
  * @param gas - The amount of Gas to attach to the call.
  * @param weight - The weight of unused Gas to use.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseBatchCreate("counter.near");
+ *
+ * near.promiseBatchActionFunctionCallWeight(
+ *  promise,
+ *  "increase",
+ *  `{"value": 5}`,
+ *  bigint("0"),
+ *  bigint("30000000000000"),
+ *  bigint("1")
+ * );
+ * ```
  */
 export function promiseBatchActionFunctionCallWeight(
   promiseIndex: PromiseIndex,
@@ -809,6 +1203,13 @@ export function promiseBatchActionFunctionCallWeight(
 
 /**
  * The number of promise results available.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.promiseResultsCount(); // -> bigint("1")
+ * ```
  */
 export function promiseResultsCount(): bigint {
   return env.promise_results_count();
@@ -840,6 +1241,13 @@ export function promiseResultRaw(promiseIndex: PromiseIndex): Uint8Array {
  * Returns the result of the NEAR promise for the passed promise index as utf-8 string
  *
  * @param promiseIndex - The index of the promise to return the result for.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.promiseResult(0); // -> `{"key": "value", "nested": {"key2": "value2"}}`
+ * ```
  */
 export function promiseResult(promiseIndex: PromiseIndex): string {
   return decode(promiseResultRaw(promiseIndex));
@@ -847,17 +1255,39 @@ export function promiseResult(promiseIndex: PromiseIndex): string {
 
 /**
  * Executes the promise in the NEAR WASM virtual machine.
+ * Consider the execution result of promise under promiseIndex as execution result of this function.
  *
  * @param promiseIndex - The index of the promise to execute.
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * const promise = near.promiseCreate(
+ *  "contract.near",
+ *  "increase",
+ *  `{"value": 5}`,
+ *  bigint("0"),
+ *  bigint("30000000000000")
+ * );
+ * near.promiseReturn(promise);
+ * ```
  */
 export function promiseReturn(promiseIndex: PromiseIndex): void {
   env.promise_return(promiseIndex as unknown as bigint);
 }
 
 /**
- * Returns sha256 hash of given value
+ * Returns sha256 hash of given value. This returns a 32 byte hash.
  * @param value - value to be hashed, in Bytes
  * @returns hash result in Bytes
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.sha256([1, 4, 18, 31, 5, 91, 224]); // -> [0, 7, 18, 94, 228, 11, 15, ...]
+ * ```
  */
 export function sha256(value: Uint8Array): Uint8Array {
   env.sha256(value, 0);
@@ -868,6 +1298,13 @@ export function sha256(value: Uint8Array): Uint8Array {
  * Returns keccak256 hash of given value
  * @param value - value to be hashed, in Bytes
  * @returns hash result in Bytes
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.keccak256([0, 24, 81, 31]); // -> [1, 3, 48, 94, 248, 11, 35, ...]
+ * ```
  */
 export function keccak256(value: Uint8Array): Uint8Array {
   env.keccak256(value, 0);
@@ -878,6 +1315,13 @@ export function keccak256(value: Uint8Array): Uint8Array {
  * Returns keccak512 hash of given value
  * @param value - value to be hashed, in Bytes
  * @returns hash result in Bytes
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.keccak512([0, 24, 81, 31]); // -> [1, 3, 48, 94, 248, 11, 35, ...]
+ * ```
  */
 export function keccak512(value: Uint8Array): Uint8Array {
   env.keccak512(value, 0);
@@ -885,9 +1329,16 @@ export function keccak512(value: Uint8Array): Uint8Array {
 }
 
 /**
- * Returns ripemd160 hash of given value
+ * Returns ripemd160 hash of given value. This returns a 20 byte hash.
  * @param value - value to be hashed, in Bytes
  * @returns hash result in Bytes
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.ripemd160([5, 14, 51, 31, 15, 69]); // -> [2, 0, 0, 0, 18, 11, 65, ...]
+ * ```
  */
 export function ripemd160(value: Uint8Array): Uint8Array {
   env.ripemd160(value, 0);
@@ -924,6 +1375,8 @@ export function ecrecover(
 
 /**
  * Panic the transaction execution with given message
+ * There's no way to panic with a utf-8 string, use "throw Error(msg)" for that
+ *
  * @param msg - panic message in raw bytes, which should be a valid UTF-8 sequence
  */
 export function panicUtf8(msg: Uint8Array): never {
@@ -947,17 +1400,34 @@ export function logUtf16(msg: Uint8Array) {
 }
 
 /**
- * Returns the number of staked NEAR of given validator, in yoctoNEAR
+ * Returns the number of staked NEAR of given validator, in yoctoNEAR.
+ * If the account is not a validator, returns 0.
+ *
  * @param accountId - validator's AccountID
  * @returns - staked amount
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.validatorStake("non-validator.near"); // -> bigint("0")
+ * near.validatorStake("validator.near"); // -> bigint("157201939492990")
+ * ```
  */
 export function validatorStake(accountId: string): bigint {
   return env.validator_stake(accountId);
 }
 
 /**
- * Returns the number of staked NEAR of all validators, in yoctoNEAR
+ * Returns the number of staked NEAR of all validators, in yoctoNEAR, in the current epoch.
  * @returns total staked amount
+ *
+ * @example
+ * ```ts
+ * import { near } from "near-sdk-js";
+ *
+ * near.validatorTotalStake(); // -> bigint("412929490100000")
+ * ```
  */
 export function validatorTotalStake(): bigint {
   return env.validator_total_stake();
@@ -974,6 +1444,8 @@ export function validatorTotalStake(): bigint {
  * `[((u256, u256), u256)]` slice.
  *
  * @returns multi exp sum
+ *
+ * @see [EIP-196](https://eips.ethereum.org/EIPS/eip-196)
  */
 export function altBn128G1Multiexp(value: Uint8Array): Uint8Array {
   env.alt_bn128_g1_multiexp(value, 0);
@@ -991,6 +1463,8 @@ export function altBn128G1Multiexp(value: Uint8Array): Uint8Array {
  * `[((u256, u256), ((u256, u256), (u256, u256)))]` slice.
  *
  * @returns sum over Fq.
+ *
+ * @see [EIP-196](https://eips.ethereum.org/EIPS/eip-196)
  */
 export function altBn128G1Sum(value: Uint8Array): Uint8Array {
   env.alt_bn128_g1_sum(value, 0);
@@ -1011,6 +1485,8 @@ export function altBn128G1Sum(value: Uint8Array): Uint8Array {
  * `[((u256, u256), ((u256, u256), (u256, u256)))]` slice.
  *
  * @returns whether pairing check pass
+ *
+ * @see [EIP-197](https://eips.ethereum.org/EIPS/eip-197)
  */
 export function altBn128PairingCheck(value: Uint8Array): boolean {
   return env.alt_bn128_pairing_check(value) === 1n;