# near-fastapi

Production-ready FastAPI service for NEAR Protocol.

This package exposes a clean REST API for common NEAR operations:

- Network status (mainnet/testnet)
- Account details and access keys
- Contract code hash
- Contract view function calls with JSON decoding

## Install

```bash
pip install near-fastapi
```

## Run

```bash
near-fastapi --host 0.0.0.0 --port 8080
```

Open docs:

- Swagger UI: `http://localhost:8080/docs`
- ReDoc: `http://localhost:8080/redoc`

## API Endpoints

- `GET /health`
- `GET /v1/networks`
- `GET /v1/status?network=mainnet`
- `GET /v1/accounts/{account_id}?network=mainnet`
- `GET /v1/accounts/{account_id}/keys?network=mainnet`
- `GET /v1/contracts/{account_id}/code-hash?network=mainnet`
- `POST /v1/contracts/{account_id}/view`

## Contract View Example

```bash
curl -X POST http://localhost:8080/v1/contracts/social.near/view \
  -H 'Content-Type: application/json' \
  -d '{
    "method": "get",
    "args": {"keys": ["near.social/root"]},
    "network": "mainnet"
  }'
```

## Python Integration Example

```python
from fastapi import FastAPI
from near_fastapi.app import create_app

app: FastAPI = create_app()
```

## NEAR Integration Notes

- Uses official NEAR RPC endpoints:
  - `https://rpc.mainnet.near.org`
  - `https://rpc.testnet.near.org`
- Returns RPC errors as clear HTTP errors.
- Validates account IDs to reduce bad requests early.

## Development

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
pytest -q
```

## License

MIT
