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

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.91
File	Size	Uploaded
near_jsonrpc_client-1.0.91.tar.gz	144.6 kB	Sep 10, 2026	Details

Built distribution (wheel)

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

Total release size: 405.0 kB

Release files / near_jsonrpc_client-1.0.91.tar.gz

Download URL	near_jsonrpc_client-1.0.91.tar.gz
Size	144.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`f17f5007d150983a92c5c8fb46d7eb0803aff582491b57d19f9ccb92d562039a`
BLAKE2b-256 checksum How to use checksums	`064d0a66f88633b6053245f7f6c36b5f95e11ce7eb355d122a8663454b7d1f2a`
Upload date	Sep 10, 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.91-py3-none-any.whl

Download URL	near_jsonrpc_client-1.0.91-py3-none-any.whl
Size	260.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`4db53d5ef405c29a17f1630d99f335ba46d2c03b32ec6133a0c688cdb5fdac4e`
BLAKE2b-256 checksum How to use checksums	`df6455f5307dd6da5f689ed0d6fc14f4d3a735e9e845ac53972342fa47e62f8d`
Upload date	Sep 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.16`