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
Metadata
1 maintainer
Release files for near-jsonrpc-client 1.0.100
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| near_jsonrpc_client-1.0.100.tar.gz | 147.0 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| near_jsonrpc_client-1.0.100-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 414.8 kB
Release files / near_jsonrpc_client-1.0.100.tar.gz
| Download URL | near_jsonrpc_client-1.0.100.tar.gz |
|---|---|
| Size | 147.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
72e24e17c605429391b22ad91f81969b4fc82e12389bb3262ba9c0256919ce9f
|
|
BLAKE2b-256 checksum How to use checksums |
c0a089663edb02153df2c7856fc36dd3bc6a0d7a5338f8bb8df69f439e2df865
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.17
|
Release files / near_jsonrpc_client-1.0.100-py3-none-any.whl
| Download URL | near_jsonrpc_client-1.0.100-py3-none-any.whl |
|---|---|
| Size | 267.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e02783c406a85b0a25576723a2f5754df162742bd226e7b55b8733611f44a0de
|
|
BLAKE2b-256 checksum How to use checksums |
ee44db7f2790fd47483fa2fd7fc7a89f7f0b12239812e7527e1f16b14e5a4847
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.17
|
Security for near-jsonrpc-client 1.0.100
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
