Add Perk in three steps

Step 1

Drop the widget into your form

Load the script once, then place <captcha-widget> where the captcha should appear. Keep the submit button disabled for now.

<script type="module"
  src="https://captcha.vperked.online/static/captchaWidget.js"
  integrity="sha384-…"
  crossorigin="anonymous"></script>

<form method="post" action="/signup">
  <input type="email" name="email" required>
  <captcha-widget
    name="captcha_token"
    endpoint="https://captcha.vperked.online"
    action="signup">
  </captcha-widget>
  <button type="submit" disabled>Create account</button>
</form>

Step 2

Only enable submit after verify

When the user finishes the check, Perk inserts a hidden token and fires captcha-verified. Turn the button on then. If anything fails, turn it back off.

<script type="module">
  const form = document.querySelector('form');
  const button = form.querySelector('button[type="submit"]');
  const widget = form.querySelector('captcha-widget');

  widget.addEventListener('captcha-verified', () => {
    button.disabled = false;
  });
  widget.addEventListener('captcha-error', () => {
    button.disabled = true;
  });
</script>

Step 3

Spend the token once, then continue

Before you create a session or write to your database, spend the token from the browser so the client IP matches verify. Use consumeToken() from the widget module—it sends X-Perk-Client: widget, CORS, and the Sec-Fetch headers Perk expects (including on cross-origin pages).

<script type="module">
  import { consumeToken } from 'https://captcha.vperked.online/static/captchaWidget.js';

  form.addEventListener('submit', async (event) => {
    event.preventDefault();
    const token = form.elements.captcha_token.value;
    if (!token) return;

    const res = await consumeToken(token, 'signup');
    const data = await res.json();
    if (!res.ok || data.status !== 'success') {
      throw new Error(data.status || 'invalid request');
    }
    // token spent — continue signup
  });
</script>

Without your own module script, load the widget with <script type="module" src="https://captcha.vperked.online/static/captchaWidget.js"></script>, then call await window.PerkCaptcha.consumeToken(token, 'signup'). On another origin, configure the endpoint first:

window.PerkCaptcha.configure({
  endpoint: 'https://captcha.vperked.online',
  action: 'signup',
});
await window.PerkCaptcha.consumeToken(token);

Raw HTTP (trusted site backend). Browser-shaped traffic should use consumeToken() instead.

POST https://captcha.vperked.online/captcha/consume
Content-Type: application/json
X-Perk-Site: https://shop.example.com
X-Perk-Key: perk_…
X-Perk-Client-IP: 203.0.113.40

{ "captcha_token": "ok:ct_…", "action": "signup" }

Check

Try it here

Click and hold the box. When it verifies, you are ready to wire the same pattern into your form.