---
name: near-jsonrpc-skill
description: Operate NEAR JSON-RPC reads through UXC with a public provider default, provider-override guidance, and read-only guardrails.
---

# NEAR JSON-RPC Skill

Use this skill to run NEAR JSON-RPC operations through `uxc` + JSON-RPC.

Reuse the `uxc` skill for shared execution and error-handling guidance.

## Prerequisites

- `uxc` is installed and available in `PATH`.
- Network access to a working NEAR RPC provider.
- This skill defaults to `https://free.rpc.fastnear.com`, which is listed on the official NEAR RPC providers page.
- Access to the curated NEAR OpenRPC schema URL:
  - `https://raw.githubusercontent.com/holon-run/uxc/main/skills/near-jsonrpc-skill/references/near-public.openrpc.json`

## Scope

This skill covers a safe read-first NEAR RPC surface:

- chain status
- account state query
- finalized block lookup
- chunk lookup by chunk hash
- gas price lookup
- validator set lookup

This skill does **not** cover:

- transaction submission methods
- signing or wallet flows
- archival assumptions for very old blocks or chunks
- deprecated `near.org` or `pagoda.co` public RPC endpoints

## Endpoint And Schema

This skill uses the public FastNear mainnet RPC by default:

- `https://free.rpc.fastnear.com`

The operation surface comes from the curated NEAR OpenRPC schema in this repo:

- `https://raw.githubusercontent.com/holon-run/uxc/main/skills/near-jsonrpc-skill/references/near-public.openrpc.json`

`uxc` JSON-RPC discovery depends on OpenRPC or `rpc.discover`. FastNear does not expose a discoverable method surface that UXC can consume directly, so this skill uses a fixed `--schema-url` link and request flow.

The official NEAR docs now treat `near.org` and `pagoda.co` RPC endpoints as deprecated. Do not use those old hosts as the default for new automation.

If the user already has a preferred provider from the official NEAR providers page, relink the same command to that provider instead of reusing the deprecated endpoints.

## Authentication

The default FastNear public RPC used by this skill does not require authentication.

If the user switches to a private NEAR provider, verify its auth model before reusing this skill unchanged.

## Core Workflow

1. Use the fixed link command by default:
   - `command -v near-jsonrpc-cli`
   - If missing, create it:
     `uxc link near-jsonrpc-cli https://free.rpc.fastnear.com --schema-url https://raw.githubusercontent.com/holon-run/uxc/main/skills/near-jsonrpc-skill/references/near-public.openrpc.json`
   - `near-jsonrpc-cli -h`

2. Inspect operation help first, then run known read methods:
   - `near-jsonrpc-cli -h`
   - `near-jsonrpc-cli query -h`
   - `near-jsonrpc-cli gas_price -h`
   - `near-jsonrpc-cli status`
   - `near-jsonrpc-cli gas_price --input-json '{"block_id":null}'`

3. Prefer narrow validation before deeper queries:
   - `near-jsonrpc-cli status`
   - `near-jsonrpc-cli block '{"finality":"final"}'`
   - `near-jsonrpc-cli query '{"request_type":"view_account","finality":"final","account_id":"near"}'`

4. Use object JSON for request objects, and `--input-json` when a method expects positional null/default params:
   - object request:
     `near-jsonrpc-cli chunk '{"chunk_id":"75cewvnKFLrJshoUft1tiUC9GriuxWTc4bWezjy2MoPR"}'`
   - positional null/default encoded from an object payload:
     `near-jsonrpc-cli gas_price --input-json '{"block_id":null}'`
     `near-jsonrpc-cli validators --input-json '{"epoch_reference":null}'`

## Recommended Read Operations

- `status`
- `query`
- `block`
- `chunk`
- `gas_price`
- `validators`

## Guardrails

- Keep automation on the JSON output envelope; do not use `--text`.
- Parse stable fields first: `ok`, `kind`, `protocol`, `data`, `error`.
- Stay on the read-only method surface by default.
- The fixed schema is required because FastNear is not directly discoverable by UXC; do not drop `--schema-url` from the linked command unless the provider proves it exposes usable OpenRPC or `rpc.discover`.
- Do not use this skill for transaction submission, signing, or wallet-authenticated flows.
- The official NEAR docs mark the old `near.org` and `pagoda.co` public RPC endpoints as deprecated. Prefer providers from the official RPC providers page instead.
- Public providers can differ in archival retention and rate limits. If `chunk` or older `block` lookups fail with unknown or garbage-collected errors, switch to a provider that explicitly supports the needed history.
- For methods such as `gas_price` and `validators` that expect positional params, use `--input-json '{"...":null}'` instead of array payloads; UXC CLI positional JSON accepts objects, not arrays.
- `near-jsonrpc-cli <operation> ...` is equivalent to `uxc https://free.rpc.fastnear.com --schema-url <near_openrpc_schema> <operation> ...`.

## References

- Usage patterns: `references/usage-patterns.md`
- Curated OpenRPC schema: `references/near-public.openrpc.json`
- NEAR RPC introduction: https://docs.near.org/api/rpc/introduction
- NEAR RPC providers: https://docs.near.org/api/rpc/providers