Register an account at hcaptcha.com, create a site, and note your Site Key (public, used client-side) and Secret Key (private, used server-side only).
Load the hCaptcha widget script https://js.hcaptcha.com/1/api.js in your page and add a div with class h-captcha and data-sitekey=YOUR_SITE_KEY; on form submission the widget populates a hidden field named h-captcha-response with the token.
Submit the h-captcha-response token to your backend alongside any form data; validate on the server before processing the form.
From your backend, make a POST request to https://api.hcaptcha.com/siteverify with Content-Type application/x-www-form-urlencoded and body parameters secret=YOUR_SECRET_KEY and response=TOKEN; optionally include remoteip for additional signal.
Parse the JSON response: success: true means the token is valid; success: false means it is invalid, already used, or expired—inspect error-codes[] for the specific failure reason and reject the request accordingly.
Tokens are single-use and must be verified promptly; do not store or replay tokens.
Known gotchas
The siteverify endpoint requires a standard URL-encoded form POST body, not JSON; sending a JSON Content-Type will result in an error response even if the parameters are correct.
The Secret Key must be kept server-side only; exposing it in client JavaScript allows anyone to forge siteverify calls and bypass protection entirely.
hCaptcha offers an accessibility mode (passerby.hcaptcha.com) for users who cannot complete visual challenges; ensure your UX provides a clear path to this option to avoid accessibility compliance issues.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp