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.83

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.83
File	Size	Uploaded
near_jsonrpc_client-1.0.83.tar.gz	138.5 kB	Aug 18, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for near-jsonrpc-client 1.0.83
File	Interpreter	ABI	Platform	Reset
near_jsonrpc_client-1.0.83-py3-none-any.whl 249.4 kB Aug 18, 2026	Python 3	none	any	Details

Total release size: 387.9 kB

Release files / near_jsonrpc_client-1.0.83.tar.gz

Download URL	near_jsonrpc_client-1.0.83.tar.gz
Size	138.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`093efd659230f630906ae26c21e345ab754a53eb342f80e5142313b6d60be534`
BLAKE2b-256 checksum How to use checksums	`003c60b0c227665a99018ffa9dc0816ab41e8553c1bacb91077c067233aa4a71`
Upload date	Aug 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.15`

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

Download URL	near_jsonrpc_client-1.0.83-py3-none-any.whl
Size	249.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`9345b8ff8dd94d44e73735819f54d3c3ada9abd4271231bbfac7036a4c9c3a89`
BLAKE2b-256 checksum How to use checksums	`af6486242bfb1ff1d8ba62f13147c2062bb1512b3bb6e8d75b1472b3bddeda80`
Upload date	Aug 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.15`