Getting Started

monapi-engine turns diverse abuse signals into one decision: allow, challenge, or block.

Core concepts

Signals

Individual observations: a blocklist hit, a disposable email domain, a missing MX record, a likely typo. Each carries the weight it contributed — every id is in the signal reference. No mailbox is ever contacted; there is no SMTP probing.

Score

Weighted sum of signals (0..100). Used for decisions.

Confidence

How much evidence there is, not how likely abuse is. 0.2 means no source had anything to say. Decisions are score-only; confidence is for you, not for the engine.

Decision

allow | challenge | block (policy-first output).

Profiles

Named thresholds and weight overrides, selected per request with?profile=. A checkout blocks earlier than a newsletter signup; a giveaway form challenges free mailboxes that a checkout waves through. Same signals, different verdict.

Quickstart

bash

git clone https://github.com/dplusf/monapi-engine
cd monapi-engine/engine
cp .env.example .env
docker compose up --build

curl http://localhost:18000/health
curl -H 'X-API-Key: dev-key-1' http://localhost:18000/v1/check/ip/1.1.1.1

API keys

Everything under /v1/* needs an X-API-Key header. Keys come from BOOTSTRAP_API_KEYS and are stored as salted hashes.

Then what

Wire it into a form

@monapi/client handles the timeout and fail-open behaviour you would otherwise write yourself.

Give it to an agent

The MCP server turns the checks into tools — including one that explains its own decisions.

Understand the answers

The signal reference says what each id means and, more usefully, when it is wrong.