Accounts / Contracts

The RPC API enables you to view details about accounts and contracts as well as perform contract calls.

Quick Reference

Method	Purpose
`view_account`	Get basic account information
`view_account_changes`	Monitor account state changes
`view_access_key`	Get the nonce and permissions of a single access key
`view_access_key_list`	List all access keys on an account
`view_gas_key_nonces`	List the parallel nonces of a gas key
`view_code`	Get deployed contract WASM code
`view_state`	Get contract storage data
`data_changes`	Monitor contract state changes
`contract_code_changes`	Monitor contract deployments
`call_function`	Execute read-only contract methods

View Account

Returns basic account information.

method: query
params: request_type: view_account, finality OR block_id, account_id

JSON
JavaScript
HTTPie

{
  "jsonrpc": "2.0",
  "id": "dontcare",
  "method": "query",
  "params": {
    "request_type": "view_account",
    "finality": "final",
    "account_id": "account.rpc-examples.testnet"
  }
}

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

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

const response = await provider.query({
  request_type: 'view_account',
  finality: 'final',
  account_id: 'account.rpc-examples.testnet',
});

http POST https://rpc.testnet.near.org \
  jsonrpc=2.0 id=dontcare method=query \
  params:='{"request_type":"view_account","finality":"final","account_id":"account.rpc-examples.testnet"}'

Example response

{
  "jsonrpc": "2.0",
  "result": {
    "amount": "999788200694421800000000",
    "block_hash": "56xEo2LorUFVNbkFhCncFSWNiobdp1kzm14nZ47b5JVW",
    "block_height": 187440904,
    "code_hash": "11111111111111111111111111111111",
    "locked": "0",
    "storage_usage": 410
  },
  "id": "dontcare"
}

View Account Changes

Returns account changes from transactions in a given account.

method: changes
params: changes_type: account_changes, account_ids, finality OR block_id

JSON
JavaScript
HTTPie

{
  "jsonrpc": "2.0",
  "id": "dontcare",
  "method": "changes",
  "params": {
    "changes_type": "account_changes",
    "account_ids": ["contract.rpc-examples.testnet"],
    "block_id": 187310139
  }
}

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

const provider = new JsonRpcProvider({ url: "https://archival-rpc.testnet.near.org" });

const response = await provider.accountChanges(
  ['contract.rpc-examples.testnet'],
  { blockId: 187310139 }
);

http POST https://archival-rpc.testnet.near.org \
  jsonrpc=2.0 id=dontcare method=changes \
  params:='{"changes_type":"account_changes","account_ids":["contract.rpc-examples.testnet"],"block_id":187310139}'

View Access Key

Returns the nonce and permissions of a single access key, given the account and the key’s public key.

method: query
params: request_type: view_access_key, finality OR block_id, account_id, public_key

JSON
JavaScript
HTTPie

{
  "jsonrpc": "2.0",
  "id": "dontcare",
  "method": "query",
  "params": {
    "request_type": "view_access_key",
    "finality": "final",
    "account_id": "account.rpc-examples.testnet",
    "public_key": "ed25519:DCkbTMS8s4kqV4nGvz5kRBdNbY9YwjjvNGNXKpAg2eFa"
  }
}

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

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

const response = await provider.query({
  request_type: 'view_access_key',
  finality: 'final',
  account_id: 'account.rpc-examples.testnet',
  public_key: 'ed25519:DCkbTMS8s4kqV4nGvz5kRBdNbY9YwjjvNGNXKpAg2eFa',
});

http POST https://rpc.testnet.near.org \
  jsonrpc=2.0 id=dontcare method=query \
  params:='{"request_type":"view_access_key","finality":"final","account_id":"account.rpc-examples.testnet","public_key":"ed25519:DCkbTMS8s4kqV4nGvz5kRBdNbY9YwjjvNGNXKpAg2eFa"}'

Example response

{
  "jsonrpc": "2.0",
  "result": {
    "nonce": 187310139000001,
    "permission": "FullAccess",
    "block_hash": "56xEo2LorUFVNbkFhCncFSWNiobdp1kzm14nZ47b5JVW",
    "block_height": 187440904
  },
  "id": "dontcare"
}

For a function-call key, permission is an object instead of the "FullAccess" string:

"permission": {
  "FunctionCall": {
    "allowance": "250000000000000000000000",
    "receiver_id": "contract.rpc-examples.testnet",
    "method_names": ["get_greeting"]
  }
}

For a gas key, permission also carries the key’s prepaid balance and number of nonce lanes (num_nonces). A full-access gas key uses GasKeyFullAccess:

"permission": {
  "GasKeyFullAccess": {
    "balance": "5000000000000000000000000",
    "num_nonces": 8
  }
}

A function-call gas key uses GasKeyFunctionCall, which is a flat object carrying the same function-call restrictions (allowance, receiver_id, method_names) as FunctionCall, alongside the gas-key balance and num_nonces:

"permission": {
  "GasKeyFunctionCall": {
    "balance": "5000000000000000000000000",
    "num_nonces": 8,
    "allowance": "250000000000000000000000",
    "receiver_id": "contract.rpc-examples.testnet",
    "method_names": ["get_greeting"]
  }
}

The nonces of the individual lanes are not included — query them with view_gas_key_nonces.

For a post-quantum ml-dsa-65 key, pass the full ml-dsa-65: public key in public_key. The network hashes it to locate the on-chain entry, so you query it exactly like an ed25519 or secp256k1 key.

View Access Key List

Returns all access keys for an account, each with its nonce and permissions.

method: query
params: request_type: view_access_key_list, finality OR block_id, account_id

JSON
JavaScript
HTTPie

{
  "jsonrpc": "2.0",
  "id": "dontcare",
  "method": "query",
  "params": {
    "request_type": "view_access_key_list",
    "finality": "final",
    "account_id": "account.rpc-examples.testnet"
  }
}

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

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

const response = await provider.query({
  request_type: 'view_access_key_list',
  finality: 'final',
  account_id: 'account.rpc-examples.testnet',
});

http POST https://rpc.testnet.near.org \
  jsonrpc=2.0 id=dontcare method=query \
  params:='{"request_type":"view_access_key_list","finality":"final","account_id":"account.rpc-examples.testnet"}'

Example response

{
  "jsonrpc": "2.0",
  "result": {
    "keys": [
      {
        "public_key": "ed25519:DCkbTMS8s4kqV4nGvz5kRBdNbY9YwjjvNGNXKpAg2eFa",
        "access_key": {
          "nonce": 187310139000001,
          "permission": "FullAccess"
        }
      },
      {
        "public_key": "ml-dsa-65-hash:7Xx2X4vHb9dG8pJ5tZqD3mN6kRfWcA1sLuYoP2eB4hT",
        "access_key": {
          "nonce": 187420021000003,
          "permission": "FullAccess"
        }
      }
    ],
    "block_hash": "56xEo2LorUFVNbkFhCncFSWNiobdp1kzm14nZ47b5JVW",
    "block_height": 187440904
  },
  "id": "dontcare"
}

Post-quantum ml-dsa-65 keys are stored on-chain by hash, so they appear here with an ml-dsa-65-hash: prefix (a base58-encoded 32-byte SHA3-256 digest) rather than the full ml-dsa-65: key. To match an entry to one of your own keys, derive its handle — the SHA3-256 of the domain-separation tag near:ml-dsa-65-pubkey-hash:v1 followed by the raw public key — and compare it against the returned value (hashing the key without that prefix will not match).

View Gas Key Nonces

Returns the current nonce of every parallel nonce lane of a gas key, given the account and the key’s public key. The array is indexed by nonce_index: the first element is lane 0, the second is lane 1, and so on. Use view_access_key to see the gas key’s balance and permission.

method: query
params: request_type: view_gas_key_nonces, finality OR block_id, account_id, public_key

JSON
JavaScript
HTTPie

{
  "jsonrpc": "2.0",
  "id": "dontcare",
  "method": "query",
  "params": {
    "request_type": "view_gas_key_nonces",
    "finality": "final",
    "account_id": "account.rpc-examples.testnet",
    "public_key": "ed25519:DCkbTMS8s4kqV4nGvz5kRBdNbY9YwjjvNGNXKpAg2eFa"
  }
}

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

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

const response = await provider.query({
  request_type: 'view_gas_key_nonces',
  finality: 'final',
  account_id: 'account.rpc-examples.testnet',
  public_key: 'ed25519:DCkbTMS8s4kqV4nGvz5kRBdNbY9YwjjvNGNXKpAg2eFa',
});

http POST https://rpc.testnet.near.org \
  jsonrpc=2.0 id=dontcare method=query \
  params:='{"request_type":"view_gas_key_nonces","finality":"final","account_id":"account.rpc-examples.testnet","public_key":"ed25519:DCkbTMS8s4kqV4nGvz5kRBdNbY9YwjjvNGNXKpAg2eFa"}'

Example response

{
  "jsonrpc": "2.0",
  "result": {
    "nonces": [
      187438921000012,
      187438921000003,
      187438921000000,
      187438921000000
    ],
    "block_hash": "56xEo2LorUFVNbkFhCncFSWNiobdp1kzm14nZ47b5JVW",
    "block_height": 187440904
  },
  "id": "dontcare"
}

Each lane starts at block_height * 10^6 from when the key was added and advances independently as transactions use it.

Querying a key that exists but is not a gas key (or does not exist at all) returns an UnknownGasKey error.

View Contract Code

Returns the contract code (Wasm binary) deployed to the account. The returned code is encoded in base64.

method: query
params: request_type: view_code, finality OR block_id, account_id

JSON
JavaScript
HTTPie

{
  "jsonrpc": "2.0",
  "id": "dontcare",
  "method": "query",
  "params": {
    "request_type": "view_code",
    "finality": "final",
    "account_id": "contract.rpc-examples.testnet"
  }
}

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

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

const response = await provider.query({
  request_type: 'view_code',
  finality: 'final',
  account_id: 'contract.rpc-examples.testnet',
});

http POST https://rpc.testnet.near.org \
  jsonrpc=2.0 id=dontcare method=query \
  params:='{"request_type":"view_code","finality":"final","account_id":"contract.rpc-examples.testnet"}'

View Contract State

Returns the state (key-value pairs) of a contract based on a key prefix (base64 encoded). Pass an empty string for prefix_base64 to return the entire state.

method: query
params: request_type: view_state, finality OR block_id, account_id, prefix_base64

By default, RPC nodes only return up to 50kB of contract state. If the contract’s state exceeds this limit, the query will return an error. To query larger state, use an archival node and paginate with prefix_base64.

JSON
JavaScript
HTTPie

{
  "jsonrpc": "2.0",
  "id": "dontcare",
  "method": "query",
  "params": {
    "request_type": "view_state",
    "finality": "final",
    "account_id": "contract.rpc-examples.testnet",
    "prefix_base64": ""
  }
}

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

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

const response = await provider.query({
  request_type: 'view_state',
  finality: 'final',
  account_id: 'contract.rpc-examples.testnet',
  prefix_base64: '',
});

http POST https://rpc.testnet.near.org \
  jsonrpc=2.0 id=dontcare method=query \
  params:='{"request_type":"view_state","finality":"final","account_id":"contract.rpc-examples.testnet","prefix_base64":""}'

View Contract State Changes

Returns state change details of a contract based on a key prefix (base64 encoded).

method: changes
params: changes_type: data_changes, account_ids, key_prefix_base64, finality OR block_id

JSON
JavaScript
HTTPie

{
  "jsonrpc": "2.0",
  "id": "dontcare",
  "method": "changes",
  "params": {
    "changes_type": "data_changes",
    "account_ids": ["contract.rpc-examples.testnet"],
    "key_prefix_base64": "",
    "block_id": 187310139
  }
}

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

const provider = new JsonRpcProvider({ url: "https://archival-rpc.testnet.near.org" });

const response = await provider.contractStateChanges(
  ['contract.rpc-examples.testnet'],
  { blockId: 187310139 },
  ''
);

http POST https://archival-rpc.testnet.near.org \
  jsonrpc=2.0 id=dontcare method=changes \
  params:='{"changes_type":"data_changes","account_ids":["contract.rpc-examples.testnet"],"key_prefix_base64":"","block_id":187310139}'

View Contract Code Changes

Returns code changes made when deploying a contract. Change is returned as a base64 encoded WASM file.

method: changes
params: changes_type: contract_code_changes, account_ids, finality OR block_id

JSON
JavaScript
HTTPie

{
  "jsonrpc": "2.0",
  "id": "dontcare",
  "method": "changes",
  "params": {
    "changes_type": "contract_code_changes",
    "account_ids": ["contract.rpc-examples.testnet"],
    "block_id": 187309439
  }
}

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

const provider = new JsonRpcProvider({ url: "https://archival-rpc.testnet.near.org" });

const response = await provider.contractCodeChanges(
  ['contract.rpc-examples.testnet'],
  { blockId: 187309439 }
);

http POST https://archival-rpc.testnet.near.org \
  jsonrpc=2.0 id=dontcare method=changes \
  params:='{"changes_type":"contract_code_changes","account_ids":["contract.rpc-examples.testnet"],"block_id":187309439}'

Call a Contract Function

Allows you to call a contract method as a view function (read-only).

method: query
params: request_type: call_function, finality OR block_id, account_id, method_name, args_base64

JSON
JavaScript
HTTPie

{
  "jsonrpc": "2.0",
  "id": "dontcare",
  "method": "query",
  "params": {
    "request_type": "call_function",
    "finality": "final",
    "account_id": "contract.rpc-examples.testnet",
    "method_name": "get_greeting",
    "args_base64": ""
  }
}

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

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

const response = await provider.query({
  request_type: 'call_function',
  finality: 'final',
  account_id: 'contract.rpc-examples.testnet',
  method_name: 'get_greeting',
  args_base64: '',
});

http POST https://rpc.testnet.near.org \
  jsonrpc=2.0 id=dontcare method=query \
  params:='{"request_type":"call_function","finality":"final","account_id":"contract.rpc-examples.testnet","method_name":"get_greeting","args_base64":""}'

Error Handling

Error Code	Description	Solution
`UnknownAccount`	Account does not exist	Check account ID spelling
`InvalidAccount`	Invalid account format	Use valid account ID (e.g., `account.near`)
`UnknownBlock`	Block not found	Use a valid block hash or height
`UnknownGasKey`	Key is not a gas key or does not exist	Check the public key and that it was added as a gas key
`GarbageCollectedBlock`	Block too old	Use archival node or more recent block
`NoContractCode`	No contract deployed	Verify the account has a deployed contract
`MethodNotFound`	Contract method does not exist	Check method name and contract ABI
`InvalidArgs`	Invalid method arguments	Verify args format and encoding

​Quick Reference

​View Account

​View Account Changes

​View Access Key

​View Access Key List

​View Gas Key Nonces

​View Contract Code

​View Contract State

​View Contract State Changes

​View Contract Code Changes

​Call a Contract Function

​Error Handling

Quick Reference

View Account

View Account Changes

View Access Key

View Access Key List

View Gas Key Nonces

View Contract Code

View Contract State

View Contract State Changes

View Contract Code Changes

Call a Contract Function

Error Handling