NEAR JSON-RPC Python Client

License Python Type Safe Release Badge

A type-safe, Pythonic client for the NEAR Protocol JSON-RPC API.

Overview
Features
Requirements
Installation
Quickstart
Basic Usage
Handling Responses & Errors
Testing
Contributing
Deployment Guide
License
References

📖 Overview

This library provides a type-safe, developer-friendly Python interface for interacting with the NEAR Protocol JSON-RPC API.

Fully typed request & response models
Clean separation between transport, RPC layer, and domain models
Designed for both scripting and production use

The client is inspired by official NEAR JSON-RPC client in Kotlin.

Module	Description
`client`	Python JSON-RPC client supporting both sync and async usage, with full NEAR RPC method wrappers (auto-generated)
`models`	Typed Python classes for RPC requests and responses using Pydantic (auto-generated)
`generator`	Tools for generating Python client and Pydantic models from NEAR’s OpenAPI specification

✨ Features

🎯 Type-Safe API All RPC requests and responses are represented as typed Python models (dataclasses / Pydantic), reducing runtime errors.

⚡ Simple & Explicit Design No magic. Each RPC method maps directly to a NEAR JSON-RPC endpoint.

🛡️ Structured Error Handling Clear distinction between:

JSON-RPC errors
HTTP errors
Network failures
Serialization issues

🔄 Sync & Async Friendly

Synchronous client for scripts & backend services using httpx.Client
Optional async client for asyncio-based applications using httpx.AsyncClient

📦 Minimal Dependencies Built on top of well-known Python libraries (httpx and pydantic).

🧪 Testable by Design Easy to mock transport layer for unit & integration tests.

⚙️ Requirements

Python 3.9+
httpx (used for both sync and async transports)
pydantic (for type-safe request/response models)

📦 Installation

pip install near-jsonrpc-client httpx pydantic

🚀 Quickstart

Async Client

import asyncio
from near_jsonrpc_client import NearClientAsync
from near_jsonrpc_models import RpcBlockRequest, BlockId, RpcBlockRequestBlockId, BlockIdBlockHeight


async def main():
    client = NearClientAsync(rpc_urls="https://rpc.mainnet.near.org")

    params = RpcBlockRequest(
        RpcBlockRequestBlockId(
            block_id=BlockId(BlockIdBlockHeight(178682261))
        )
    )

    block = await client.block(params=params)
    print(block)

    await client.close()


asyncio.run(main())

Sync Client

from near_jsonrpc_client import NearClientSync
from near_jsonrpc_models import RpcBlockRequest, BlockId, RpcBlockRequestBlockId, BlockIdBlockHeight

client = NearClientSync(rpc_urls="https://rpc.mainnet.near.org")

params = RpcBlockRequest(
    RpcBlockRequestBlockId(
        block_id=BlockId(BlockIdBlockHeight(178682261))
    )
)

block = client.block(params=params)
print(block)

client.close()

📝 Basic Usage

Create request models for each RPC method.
Call the method on the appropriate client (async or sync).
Receive typed response models.

from near_jsonrpc_models import RpcBlockRequest, RpcBlockRequestBlockId, BlockIdBlockHeight, BlockId

params = RpcBlockRequest(RpcBlockRequestBlockId(block_id=BlockId(BlockIdBlockHeight(178682261))))
response = client.block(params=params)
print(response)

⚠️ Handling Responses & Errors

The client raises structured exceptions:

RpcError – returned from NEAR JSON-RPC
RpcHttpError – HTTP errors with status code and body
RpcTimeoutError – request timeout
RpcClientError – unexpected or invalid responses

Example:

from near_jsonrpc_client import RpcError, RpcHttpError, RpcTimeoutError, RpcClientError

try:
    block = client.block(params=params)
except RpcError as e:
    print(f"RPC error: {e.error}")
except RpcHttpError as e:
    print(f"HTTP error: {e.status_code}, {e.body}")
except RpcTimeoutError as e:
    print("Request timed out")
except RpcClientError as e:
    print("Invalid response", e)

🧪 Testing

Simply run pytest to execute all tests.
The transport layer (HttpTransportAsync or HttpTransportSync) is mocked internally, so no actual network calls are made.

🤝 Contributing

Fork the repository
Create a feature branch
Submit a pull request with tests

📜 License

This project is licensed under the Apache-2.0 License. See LICENSE for details.

📦 Deployment Guide

For detailed instructions on project structure, CI/CD workflow, versioning, and deployment steps, see the DEPLOYMENT.md file.

📚 References

Release files for near-jsonrpc-client 1.0.92

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for near-jsonrpc-client 1.0.92
File	Size	Uploaded
near_jsonrpc_client-1.0.92.tar.gz	148.6 kB	Sep 11, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for near-jsonrpc-client 1.0.92
File	Interpreter	ABI	Platform	Reset
near_jsonrpc_client-1.0.92-py3-none-any.whl 267.2 kB Sep 11, 2026	Python 3	none	any	Details

Total release size: 415.8 kB

Release files / near_jsonrpc_client-1.0.92.tar.gz

Download URL	near_jsonrpc_client-1.0.92.tar.gz
Size	148.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`fc6645a0c16dd37ea500e713923979c62fc4d4783e6576dd772058b778a40fa3`
BLAKE2b-256 checksum How to use checksums	`95fa8b2f005cb36810b8928e9726e948c4bb814afc63280513c44812e39931f6`
Upload date	Sep 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.16`

Release files / near_jsonrpc_client-1.0.92-py3-none-any.whl

Download URL	near_jsonrpc_client-1.0.92-py3-none-any.whl
Size	267.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`86776f1a2a22ce726638907e6ad0f6b7ef02a7b8a46018dd641af2b7fdf0aca2`
BLAKE2b-256 checksum How to use checksums	`28c9512842b56f4724207e0cd12a187034473bd61fb037203f5d14d768ee3343`
Upload date	Sep 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.16`