# Native Balance Check v0.2

A small, read-only EVM operations check for a public address. It returns one JSON object and an exit code so an existing scheduler can distinguish low native balance from unavailable RPC data.

Python 3.10 or newer; standard library only. MIT licensed. This download contains the complete source, an English quick start, Chinese documentation, synthetic examples and 35 local tests. Development and documentation are maintained by an AI agent acting for the project owner.

## Try it without a network connection

Extract the ZIP, then open a terminal in the `native-balance-check` directory containing `monitor.py`. In the starter kit, this directory is one level below `START-HERE.txt`.

```sh
python3 monitor.py --demo
python3 -m unittest discover -s tests -v
```

The demo uses synthetic data. No wallet software or private key is needed.

## Configure a real check

Copy `config.example.json` to `config.json`. Supply your public address, chain ID, minimum balance as a decimal string, and maximum acceptable block age. The current release supports native assets with 18 decimals.

Set `MONITOR_RPC_URL` to your own trusted HTTPS JSON-RPC endpoint in your local environment, then run:

```sh
python3 monitor.py --config config.json --total-timeout 5
```

Keep RPC credentials on your own machine. The endpoint receives the requested public address and your IP address. The tool does not print the endpoint or raw provider error messages.

## Interpret the result

| Exit code | Meaning | Typical status |
| --- | --- | --- |
| 0 | Healthy data and balance at or above your threshold | `ok` |
| 1 | Healthy data but balance below your threshold | `low_balance` |
| 2 | Configuration or RPC data could not be used | `config_error`, `wrong_chain`, `stale_rpc`, `rpc_error` |

The threshold is an operations setting chosen by you. The output is a point-in-time observation of one provider. An RPC failure is reported as unavailable data, never converted into a zero balance.

## Time and request limits

The CLI defaults to a five-second total deadline; `--total-timeout` accepts 1–60 seconds. It bounds the complete check with a worker process, including multiple requests and slow responses. Timeout returns `rpc_error` with `total_timeout` and exit code 2. Callers importing `check()` directly must enforce their own total deadline.

The check makes at most four requests: `eth_chainId`, `eth_blockNumber`, `eth_getBlockByNumber`, and `eth_getBalance` at the selected block. It uses integer wei internally and decimal strings in output. Redirects, truncated responses and responses larger than 1 MiB are rejected; HTTP 429/503 are errors without automatic retry.

## Scheduling example

After configuring the endpoint in a private environment file, a scheduler can invoke the CLI and route codes 1 and 2 to different alerts. Keep the exit code intact when piping output. This release supplies the check itself; scheduling and notification policy belong to your existing operations system.

## Scope

One public address, one provider, native balance only. It does not sign transactions, hold funds or provide trading signals. Multi-provider validation, ERC20 balances, reorganization finality, alert delivery and historical storage are outside this release.

The test suite covers successful results, wrong chains, stale blocks, malformed responses, HTTP errors, redirects, oversized/truncated responses, slow headers and bodies, process cleanup, total deadlines and CLI exit codes. `deadline-validation.json` records the v0.2 validation results. Review the source and test suite before relying on the output in your own environment.

## License and contact

See `LICENSE` for the MIT license. Project site: https://smallops.top/ . Questions about this download: swedensweden505@gmail.com. Share a public error category or a redacted example; keep account and RPC credentials private.