Skip to content

README.md

Latest commit

 

History

History
220 lines (147 loc) · 5.82 KB

README.md

File metadata and controls

220 lines (147 loc) · 5.82 KB

NEAR JSON-RPC Python Client

Build Status License Python Type Safe Release Badge

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

Table of contents

📖 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