NEAR JSON-RPC Python Client
A type-safe, Pythonic client for the NEAR Protocol JSON-RPC API.
Table of contents
- 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-RPCRpcHttpError– HTTP errors with status code and bodyRpcTimeoutError– request timeoutRpcClientError– 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
pytestto execute all tests. - The transport layer (
HttpTransportAsyncorHttpTransportSync) 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
1 maintainer
Release files for near-jsonrpc-client 1.0.86
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| near_jsonrpc_client-1.0.86.tar.gz | 142.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| near_jsonrpc_client-1.0.86-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 400.5 kB
Release files / near_jsonrpc_client-1.0.86.tar.gz
| Download URL | near_jsonrpc_client-1.0.86.tar.gz |
|---|---|
| Size | 142.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e3b1d055878856d0f09a12ea663325b161721dea5c39028286363778e2bbe39b
|
|
BLAKE2b-256 checksum How to use checksums |
dddf384f303e6b56c6ad8c82b03b4586c0c97da2415f96b0230b23b1c18535a7
|
| Upload date | |
|
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.86-py3-none-any.whl
| Download URL | near_jsonrpc_client-1.0.86-py3-none-any.whl |
|---|---|
| Size | 257.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
304ae5be27337d32880c3cbe537ab9cf2717a6842f28ec31880d3cc79b86daef
|
|
BLAKE2b-256 checksum How to use checksums |
9d2837138b6bf91fb0e498bc707d333a22976b2d93732b8ae0388e7c16b6a0d4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.16
|
