Integration docs

Two steps: embed the widget on your form, then verify the token from your backend. Works with any stack.

1. Embed the widget

Add the script and put data-botwall on the form you want to protect. The widget injects a hidden botwall-token field on submit.

<script src="https://botwall.aiskillhub.info/botwall.js"
        data-site-key="pk_live_xxx" defer></script>

<form data-botwall action="/api/signup" method="POST">
  <input name="email" type="email" required />
  <button type="submit">Sign up</button>
</form>

Hardening tip: pin the script with Subresource Integrity — integrity="sha384-…" crossorigin="anonymous". We publish the current hash on this page with every release.

2. Verify server-side

On your backend, read botwall-token from the submitted form and POST it with your secret key. Never expose the secret key to the browser.

// Node.js example
const r = await fetch("https://botwall.aiskillhub.info/api/v1/siteverify", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    secret: process.env.BOTWALL_SECRET,   // your secret key
    token:  req.body["botwall-token"],
  }),
});
const v = await r.json();
// { success, verdict: "allow"|"review"|"block", score, reasons, ... }
if (v.verdict === "block") return res.status(403).send("Blocked");
if (v.verdict === "review") flagForManualReview(req.body.email);

API reference

POST /api/v1/challenge

Called by the widget (public). Scores signals and returns an opaque token.

Request:  { "siteKey": "pk_live_xxx", "signals": { ... } }
Response: { "token": "bwt_...", "ttl": 300 }

POST /api/v1/siteverify

Called by your backend (server-to-server). Resolves a token to a verdict and counts one verification. Accepts JSON or form-encoded bodies, or a Bearer secret. A token can only be verified once.

Request:  { "secret": "<your secret key>", "token": "bwt_..." }
Response: {
  "success": true,
  "verdict": "allow",
  "score": 0.91,
  "action": "submit",
  "hostname": "yourapp.in",
  "reasons": ["looks_human"],
  "quota_exceeded": false,
  "challenge_ts": "2026-06-01T..."
}

Verdict bands

• allow — score ≥ 0.60. Let it through.
• review — 0.30–0.60. Add friction (email verify, manual review).
• block — score < 0.30, honeypot filled, or headless detected.

Privacy

We never collect WebGL/canvas/font fingerprints or device IDs. We hash IPs with a salt and never store raw addresses, form contents, or PII — only a non-identifying signal summary and the verdict. Data is resident in India.